All integration guidesQuickstart

Adopter quickstart: zero to a governed recall

The shortest path from an empty environment to a working, policy-enforced recall call — embedded in Python, over HTTP, and from an MCP client such as Claude or Codex.

What recall is

Recall is a governed retrieval call. You ask Heartwood for the memories relevant to a query, and it returns only what the calling principal’s policy allows — memories the caller may not see are never returned, and never counted in the response. Every result carries source IDs and a validated provenance signature, so an agent can cite where an answer came from. This guide gets you to a working recall three ways: embedded in a Python process, over HTTP from a warm local service, and from an MCP client. Pick the one that matches how your agent runs.

1 · Install

Heartwood is a Python package (Python 3.11+). The recall extra pulls in the embedder and vector index; the mcp extra adds the MCP server.

bash

python -m pip install "heartwood-memory[recall,mcp]"

# Confirm the installed version (0.1.2 or newer):
python -c "import importlib.metadata as m; print(m.version('heartwood-memory'))"

2 · Your first recall (embedded Python)

The fastest path — no server, no token. Open a store, write one governed memory, and recall it. remember() signs provenance, applies the policy envelope, and writes an audit event; recall() enforces that policy on the way out. The result is a dict with a results list; each item carries its source_ids and provenance so the answer stays attributable.

python

from heartwood import Heartwood, principal_from

hw = Heartwood(path="./heartwood.db", tenant="tenant:ops")

# Write one governed memory (provenance-signed, policy-scoped, audited).
hw.remember(
    "Refunds over $500 require finance approval.",
    subject="policy:refunds",
    created_by="agent:support",
)

# Recall under policy. The caller is an explicit principal.
result = hw.recall(
    "what is the refund policy?",
    principal=principal_from("agent:support", tenant="tenant:ops"),
    k=5,
)
for item in result["results"]:
    print(item)

3 · Recall over HTTP (warm service)

For agent loops and hooks that need sub-500ms recall, run the warm service — it keeps the store, index, embedder, and reranker hot in one process. Bind it to loopback and protect it with a bearer token. Set the token in the environment; the CLI --token flag is deprecated because argv can leak secrets. serve-recall runs in the foreground, so start it in its own shell.

bash

# A high-entropy bearer token, kept in the environment — never in argv or git.
export HEARTWOOD_RECALL_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

# Start the warm recall service on loopback (it reads the token from the env):
python -m heartwood.cli serve-recall --db ./heartwood.db --tenant tenant:ops --host 127.0.0.1 --port 8765

# In another shell, confirm it is up (no auth required for /health):
curl -sS http://127.0.0.1:8765/health
# -> {"ok":true,"service":"heartwood-recall"}

4 · Call POST /recall

With the service running and HEARTWOOD_RECALL_TOKEN exported, send the query. When the service is started with a token, the caller’s tenant, roles, and clearance are bound to that credential — so the request body only needs the query and how many results (k) you want; identity cannot be widened from the payload. Running without a token (pure loopback dev)? Then include principal_id and tenant in the body — they set the principal only when no credential is configured. The JSON response includes recall_id, latency_ms, index_lag, result_count, the results array (each with source IDs and provenance validity), and a models block naming the embedder, reranker, and index.

bash

curl -sS -X POST http://127.0.0.1:8765/recall -H "Authorization: Bearer $HEARTWOOD_RECALL_TOKEN" -H "Content-Type: application/json" -d '{"query":"what is the refund policy?","k":5}'

5 · Recall from Claude or Codex (MCP)

To give an MCP client governed memory tools, run Heartwood’s MCP server over local stdio. The server is fail-closed: with no allowlist set it exposes only the read-only subset — recall, explain_recall, health. Name additional tools explicitly to opt in to writes (remember) or erasure (forget). Use the absolute path to your virtualenv’s Python, not a bare python, so the client launches the right interpreter every time.

json

{
  "mcpServers": {
    "heartwood-memory": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "heartwood.adapters.mcp_server"],
      "env": {
        "HEARTWOOD_DB_PATH": "./heartwood.db",
        "HEARTWOOD_TENANT": "tenant:ops",
        "HEARTWOOD_MCP_ALLOWED_TOOLS": "recall,explain_recall,health"
      }
    }
  }
}

Codex clients

Codex uses ~/.codex/config.toml with an [mcp_servers.heartwood] block and a [memories] block (disable_on_external_context = true, generate_memories = false) so Heartwood stays the only durable store. See the Codex quickstart in the source-available core for the exact config and allowlist patterns.

toml

[mcp_servers.heartwood]
command = "/absolute/path/to/.venv/bin/python"
args = ["-m", "heartwood.adapters.mcp_server"]
env = { HEARTWOOD_DB_PATH = "./heartwood.db", HEARTWOOD_TENANT = "tenant:ops", HEARTWOOD_MCP_ALLOWED_TOOLS = "recall,explain_recall,health" }
startup_timeout_sec = 45
enabled_tools = ["recall", "explain_recall", "health"]

[memories]
disable_on_external_context = true
generate_memories = false

6 · Managed gateway (optional)

Prefer a hosted endpoint to running the service yourself? Heartwood operates a managed recall gateway. Each tenant is provisioned its own host — <your-tenant>.recall.heartwoodmemory.com on port 13476 — and a per-organization bearer token. The call contract is identical to the local service: POST /recall with an Authorization: Bearer header. Provisioning is not self-serve today; request access through the Team tier or as a design partner.

bash

# Same contract, managed host + org token (both issued at provisioning):
curl -sS -X POST https://YOUR-TENANT.recall.heartwoodmemory.com:13476/recall -H "Authorization: Bearer $HEARTWOOD_RECALL_TOKEN" -H "Content-Type: application/json" -d '{"query":"what is the refund policy?","k":5}'

7 · Go deeper

The sibling guides at /docs/integrations pick up where this leaves off: "Low-latency warm recall" for production tuning and the full HTTP surface; "Governed MCP memory server" for the complete tool allowlist and write/erasure patterns; "Import a Markdown memory corpus" to build a store from notes you already keep; "Tenant-aware bulk writes & recall" for the ergonomic Python API; and "End-to-end onboarding" for the full pre-cutover checklist. The complete API reference and the executable trust suite live in the source-available core, linked below.

Adapted from docs/integrations (mcp-quickstart, warm-recall, codex-quickstart) in the source-available core.

Install Heartwood View package on PyPI