MCP Setup

AideMemo exposes the same memory store through MCP so agents can search and write memory as tools. For the complete tool inventory, see Feature Inventory. For guidance on choosing the right tool per turn, see Agent Workflows.

Stdio MCP

Use stdio MCP for local agents.

aidememo mcp

Example Codex config:

[mcp_servers.aidememo]
command = "aidememo"
args = ["--backend", "libsqlite", "--store", "/absolute/project/_meta/wiki.sqlite", "mcp"]

[mcp_servers.aidememo.env]
AIDEMEMO_SOURCE_ID = "project:my-app"
AIDEMEMO_ACTOR_ID = "codex:account-a"

Claude Code standalone registration:

aidememo --store /absolute/project/_meta/wiki.sqlite mcp-install \
  --target claude \
  --source-id project:my-app \
  --actor-id claude:local

This uses Claude Code's current CLI argument order and pins the resolved store. The bundled Claude plugin is an alternative that also includes focused skills and read-only hooks. Hermes, Cursor, OpenClaw, and OpenCode also have installer targets. pi is intentionally skill-only because it does not accept MCP. See Coding Agent Setup for the complete matrix.

Authenticated remote handoff profiles

Install each isolated Codex account separately when handoff state should live in one remote SSOT project:

aidememo auth login https://memory.example.com \
  --profile codex-p1 --project-id aidememo --token-file /secure/p1.token
aidememo --store /absolute/project/_meta/wiki.sqlite mcp-install \
  --target codex --codex-home /profiles/codex-p1 \
  --source-id project:aidememo --remote-profile codex-p1

aidememo auth login https://memory.example.com \
  --profile codex-p2 --project-id aidememo --token-file /secure/p2.token
aidememo --store /absolute/project/_meta/wiki.sqlite mcp-install \
  --target codex --codex-home /profiles/codex-p2 \
  --source-id project:aidememo --remote-profile codex-p2

The installer authenticates to the server, derives AIDEMEMO_ACTOR_ID from the persisted bearer binding, and pins mcp --remote-profile NAME in that account's config. It rejects a caller-provided actor override and refuses to copy one remote credential profile into several Codex homes. Run the command once per account, then restart that agent so it reloads MCP configuration.

In this connected hybrid mode, aidememo_handoff previews from the embedded store and sends through the remote SSOT when dispatch=true. aidememo_handoff_inbox routes list, outbox, show/status, accept, and return to the authenticated server. Other memory tools continue to use the pinned local store; a receiver result fact is uploaded as canonical evidence during return. The server must be reachable at install, MCP startup, and remote handoff calls. Use aidememo replica pull --remote-profile NAME outside the MCP process when an offline canonical exact-read cache is needed. Pull bootstraps atomically and then applies revision-pinned changes. The resulting <store>.replica.sqlite is separate from the pinned embedded search store and is not refreshed implicitly at MCP startup. HTTP mcp-serve, retrieval-index replicas, and offline writes are not part of this profile path yet.

HTTP MCP server

Use HTTP when multiple agents should share one warm process:

aidememo --store ~/.aidememo/team.sqlite mcp-serve --port 3000

Then point MCP clients at:

http://127.0.0.1:3000/mcp

HTTP mode is still useful for warm model reuse and shared writes. It is especially recommended for redb stores, where only one writer process can hold the database lock at a time.

For a network-exposed shared store, bind each bearer token to one source and writer identity instead of giving every client the same unscoped token:

/etc/aidememo/token-bindings.json

{
  "tokens": [
    {
      "token": "replace-with-a-random-secret",
      "source_id": "project:my-app",
      "actor_id": "codex:account-a"
    }
  ]
}

chmod 600 /etc/aidememo/token-bindings.json
aidememo --store ~/.aidememo/team.sqlite mcp-serve \
  --bind 0.0.0.0 \
  --auth-bindings-file /etc/aidememo/token-bindings.json

AIDEMEMO_MCP_AUTH_BINDINGS_FILE is the environment-variable equivalent. The file may be either the wrapped {"tokens": [...]} object shown above or a top-level JSON array. Every token, source_id, and actor_id is trimmed and must be non-empty, and token values must be unique. --auth-bindings-file cannot be combined with --auth-token or --auth-token-file; an explicit CLI auth option takes precedence over the auth environment variables.

For a bound token, the server injects the configured source_id and actor_id into every MCP tool call and rejects a caller-supplied mismatch, including overrides inside aidememo_fact_add_many items. Bound tokens cannot use the unscoped /sync/since or /admin/status endpoints; /health returns only the health and semantic-prewarm state. Keep the existing --auth-token-file mode for a trusted, unscoped administrator. A single-token administrator is not source-bound: that client may choose source_id and actor_id in tool arguments and can use the global status and sync endpoints.

mcp-serve itself speaks plain HTTP. Bearer binding provides identity and scope enforcement, not transport encryption. For any non-loopback deployment, put the server behind a TLS-terminating reverse proxy or an encrypted private tunnel and restrict direct access to the backend port.

Core tools

Most agent workflows only need these tools:

Tool	Use when
aidememo_workflow_start	A task starts from an issue, PR, ticket, or sparse prompt
aidememo_context	The agent needs opening-turn project context
aidememo_query	The agent needs a focused topic dive
aidememo_search	The agent needs pinpoint retrieval
aidememo_aggregate	The agent needs exact counts, totals, date sets, or timelines
aidememo_session_canvas	The agent is resuming a long tracked workflow
aidememo_handoff	An orchestrator is routing the tracked workflow to another agent or profile
aidememo_handoff_inbox	Receiver list/accept/return plus sender outbox/status for a session assignment
aidememo_profile_export	The agent needs a compact read-only project profile
aidememo_fact_add	The agent learned a new fact
aidememo_fact_add_many	The agent learned several facts and should batch them

Recommended agent pattern

At the start of a ticket:

{
  "title": "Fix Redis timeout in worker",
  "body": "Worker jobs intermittently time out against Redis.",
  "source": "github:org/app#123",
  "source_id": "team-a",
  "bm25_only": true
}

Call:

aidememo_workflow_start

Then use the returned session_id when adding follow-up facts:

{
  "content": "Lesson: the timeout was DNS resolution, not pool size.",
  "fact_type": "lesson",
  "entities": ["Redis", "Worker"],
  "session_id": "session-..."
}

Call:

aidememo_fact_add

Handoff is currently an unreleased main feature. Public v0.1.0 MCP servers and Hermes packages do not expose these tools.

Start with Hand off a tracked task for the user-facing round trip. The calls below document the lower-level MCP envelope.

Before another worker takes over, call aidememo_handoff:

{
  "session_id": "session-...",
  "from_actor": "codex-one",
  "to_actor": "codex-two",
  "from": "codex/coding",
  "to": "codex/reviewer",
  "focus": "Verify the patch and run the focused regression test",
  "done_when": "Focused tests pass and review findings are recorded",
  "source_id": "team-a",
  "dispatch": true
}

Without dispatch, the result is the existing read-only Markdown preview. With dispatch, AideMemo additionally stores a pending pointer that the receiving account pulls through aidememo_handoff_inbox. Use action: "list", then action: "accept" with the returned handoff_id; accept returns the packet rendered from the current session plus a structured resume environment. The installable worker also passes a unique claim_id; only that claim may retry an active automatic assignment. After a fact-linked failed return, a new claim may reclaim it and increments attempt_count. The receiver persists its evidence fact and calls action: "return" with result_fact_id and outcome. The sender uses action: "outbox" or action: "status" to recover that link. outcome: "failed" remains accepted; no retry is scheduled by AideMemo. Return fails closed unless the fact belongs to the handed-off session and exact source scope and carries the receiving actor as writer provenance. Legacy action: "complete" is an evidence-free acknowledgement and does not prove task success.

session_id identifies task continuity, source_id scopes retrieval, actor_id names a user-assigned account/installation, and agent/profile names describe runtime role. Actor ids and profiles are routing metadata, not authentication. The assignment record contains no topic, offset, consumer group, retry state, or copied content payload.

The SDK exposes both consumption shapes:

packet = memory.handoff_packet(..., from_actor="codex-one",
                               to_actor="codex-two", dispatch=True)
pending = memory.handoff_inbox(actor_id="codex-two")
accepted = memory.handoff_accept(pending[0]["handoff_id"], actor_id="codex-two")
[result_id] = memory.remember([
    {"content": "Focused tests pass", "entities": ["Release"]}
])
memory.handoff_return(pending[0]["handoff_id"], result_id,
                      outcome="succeeded", actor_id="codex-two")
memory.handoff_outbox(actor_id="codex-one", include_completed=True)

Hermes' aidememo_handoff tool returns the same structured envelope rather than a JSON-encoded Markdown string.

Source scoping

Use source_id when a shared store contains multiple teams, projects, users, or agents.

aidememo --backend libsqlite --store ~/.aidememo/team.sqlite \
  mcp-install --target codex --source-id team-a --actor-id codex-one

MCP tools then default to that source namespace when the client does not pass an explicit source_id; inbox calls similarly fall back to the installed AIDEMEMO_ACTOR_ID. The installed command also pins the selected storage backend and resolved store path so an agent process does not drift back to a different config default or working directory. Use --actor-id independently when multiple agent profiles share that namespace and writes need provenance.

Source scoping applies consistently to fact search/list/get, pinned context, entity reads, graph traversal/path/export, and ID-based fact mutations. A source-scoped entity result is returned only when that entity has facts in the source; global entity metadata without source provenance is omitted. Identical fact content deduplicates within one source, while the same text in two sources keeps two independent fact IDs. Graph relations have their own source provenance: a scoped graph read accepts only an exact relation namespace match, so legacy unscoped edges and another source's evidence, weight, or relation type are not exposed. Use token bindings above when the client must not be allowed to choose or override its own scope.

This is a strong partition for cooperating agents in one trusted team store, not a full hostile multi-tenant database boundary. Entity names and entity types intentionally form a shared ontology across sources. If tenants must not share even that ontology or must be protected from one another's resource use, give them separate stores (or separate AideMemo processes) instead. See Shared Memory Layer for the deployment shapes, trust boundary, and production checklist behind this choice.

For isolated Codex accounts, repeat --codex-home and --actor-id while pointing every profile at the same explicit store. See Share Memory Across Codex Profiles.

Troubleshooting

Symptom	Fix
Agent cannot see tools	Confirm MCP config path and restart the agent
Claude isolated profile cannot see its skill	Set CLAUDE_CONFIG_DIR before skill install --target claude
One Codex profile cannot see AideMemo	Install into its active CODEX_HOME, or pass --codex-home explicitly
Hermes isolated profile cannot see AideMemo	Set HERMES_HOME before installing both the skill and MCP entry
pi suggests an MCP step	Update AideMemo and use skill install --target pi only
command not found: aidememo	Use an absolute path in MCP config
Agent opens the wrong store	Reinstall with global --store; aidememo doctor reports Codex store mismatches
Store lock errors	Use one aidememo mcp-serve process for shared writes
Wrong project context appears	Add or verify source_id scoping