Agent Memory and MCP

Coding agents forget everything between sessions, and every agent forgets separately: a decision one Claude Code session records is invisible to Codex an hour later and to OpenCode next week. Agent Memory is one local engine every coding-agent host shares through the same MCP binary and the same profile — no host receives host-specific memory semantics.

Five verbs, three collections

The product is five verbs — store, journal, recall, forget, status — over three physically separate search collections: personal, work, and journal. Work holds user/project decisions; journal holds a model's first-person reflection and is always rendered as historical model thought, never as user instruction or authority. Every memory is one bounded record:

{
  "project": "basecamp/omarchy",
  "scope": "project",
  "kind": "decision",
  "layer": "work",
  "agent": "claude",
  "harness": "claude-code-cli",
  "model": "anthropic/claude-sonnet",
  "text": "Use omarchy-pkg-add instead of invoking pacman directly",
  "ttl": null
}

text is 1 to 4,096 UTF-8 bytes; a memory's identity is derived from project, layer, and text, so storing the same sentence twice in the same project and layer is one memory, not two. scope is project (default, isolated per project — two projects never observe each other's memories through any tool surface) or global (lives in the reserved project _global, surfaces in every recall, clearly labeled). kind is one of decision, command, constraint, fact, note. ttl is an optional lifetime, 1 second to 10 years, evaluated on the engine's clock — an expired memory never appears in a recall again.

What gets captured, and what fails closed

Host lifecycle hooks make recall proactive: project memory is injected before the host processes a prompt. Capture is deterministic and conservative — only explicit decisions, constraints, facts, and a narrow allowlist of successful reusable commands are persisted; full prompts, full responses, reasoning, tool output, and detected secrets are never stored automatically.

The proactive bridge rejects detected personally identifiable information — email addresses, phone numbers, postal-address labels, government identifiers, payment cards, IP/MAC addresses, UUIDs, home directory paths, and likely high-entropy credentials. Detection is deliberately fail-closed: a candidate matching any sensitive-data rule is discarded rather than partially redacted. Project identifiers themselves are stored as local keyed-purpose BLAKE3-derived names, never repository URLs or filesystem paths.

When the daemon is temporarily unavailable, already-sanitized capture candidates enter an owner-only durable spool under $XDG_STATE_HOME/hyphae/agent-hooks/ — content-identified, written with create-new and fsync semantics, deduplicated across retries, and drained opportunistically through the local socket. A hook failure never blocks a host from continuing without memory.

hyphae agent: setup, configure, status

hyphae agent setup [--enable-service | --no-service]
hyphae agent status | doctor | backup | upgrade | migrate-domains | remove
hyphae agent restore --backup <ARCHIVE>
hyphae agent configure <claude|codex|opencode|pi> [--access <read|write>] [--apply]
hyphae agent hook --host <claude|codex|opencode|pi>  # bounded JSON on stdin
hyphae agent purge-data [--yes]

setup is idempotent: it initializes the directory at ~/.local/share/hyphae/agent-memory/, provisions the three physically separate collections, creates scoped principals, and issues role-ceilinged keys under ~/.config/hyphae/credentials/ (mode 0600), with an opt-in systemd user unit. configure emits read-only host registration by default; --access write explicitly adds store and forget, and --apply installs the registration through the host's own supported interface — the configuration it writes carries only a credential file path, never a secret. remove deletes the service and credentials but never data; only purge-data deletes data, requires interactive confirmation, and — like restore — refuses while the service owns the directory. Backup and restore follow the same verified-archive pattern as the rest of Hyphae: agent backup prints the archive path and its digest; agent restore verifies the archive before replacing the directory.

hyphae mcp: the stdio adapter

hyphae mcp is a bounded stdio adapter for an already running managed Native local or HTTP v2 service — it never opens a data directory or starts a listener itself. It speaks newline-delimited JSON-RPC 2.0, advertises MCP revision 2025-06-18, and is read-only unless explicitly told otherwise. The credential establishes the only authority used by every tool in that process; tool arguments and model-generated prompt input can never supply a different key, role, or permission, and unknown input fields fail closed.

hyphae serve --data-dir ./hyphae-data \
  --endpoint ./hyphae.sock \
  --http-bind 127.0.0.1:8787 \
  --native-api-key-auth

hyphae mcp --endpoint ./hyphae.sock \
  --native-api-key-file ./auditor.key

Full profile: eight read-only tools, three behind --allow-ingest

Tool	Requires
`hyphae_native_capabilities`	`discover`
`hyphae_native_security_status`	`security.read` at Instance
`hyphae_native_security_principals`	`security.read` at Instance
`hyphae_native_search_lexical`	`search.execute`
`hyphae_native_search_collection`	`search.execute`
`hyphae_native_prove_search`	`proof.generate`
`hyphae_native_verify_proof`	none — trustless, verifies entirely inside the adapter process
`hyphae_native_memory_recall`	`search.execute` (plus `proof.generate` with `prove`)
`hyphae_native_search_ingest` *	`data.write` and `search.execute`
`hyphae_native_memory_store` *	`data.write` and `search.execute`
`hyphae_native_memory_forget` *	`data.write` and `search.execute`

Tools marked * are listed only when the adapter starts with --allow-ingest — the flag only exposes the tools; each write still requires a key whose durable authority carries data.write (the built-in Writer role). A Reader or Auditor key gets a typed authorization_denied, not a silent skip. The checked-in agent plugin never passes --allow-ingest and stays read-only.

Memory profile: the five-verb surface

hyphae mcp --profile memory swaps the full registry for the Agent Memory five-tool surface over the three separated collections, set with --personal-memory-collection, --work-memory-collection, and --journal-memory-collection. recall and status are always listed; store, journal, and forget need --allow-write and a key with write authority. The bundled plugin's .mcp.json starts the full profile above, not this one — wire a host to the memory profile with hyphae agent configure <host> instead.

Installing the plugin

One plugin directory supports both Codex and Claude Code; both start the same hyphae mcp stdio server from a shared .mcp.json.

# Claude Code, local development
claude --plugin-dir ./plugins/hyphae

# Claude Code, marketplace installation
/plugin marketplace add Hyphae-Research-Foundation/hyphae
/plugin install hyphae@hyphae

Prerequisites: the exact hyphae binary on PATH, a bootstrapped Native HTTP v2 service on http://127.0.0.1:8787, and an Auditor-role principal at Instance scope whose key file path is set as HYPHAE_NATIVE_API_KEY_FILE before the agent host starts. The checked-in plugin accepts plaintext HTTP only at the canonical loopback origin; a remote --base-url override must be https://.

The authority model underneath

Every MCP tool's authority traces back to Hyphae's own RBAC model (Operations covers the full picture). The relevant built-in roles for an agent host:

Role	Covers	Excludes
`auditor`	metadata, telemetry, security metadata, audit, backup/proof verification	record contents, every mutation
`reader`	application read, search, and proofs	every mutation and administrative operation
`writer`	application read/write and search	DDL, maintenance, security administration

An Auditor key covers the capability and security tools; the search and recall tools need search.execute, which Reader carries alongside proof.generate; the write-scoped ingest, store, and forget tools need data.write, which only Writer carries. Issue the key whose durable authority matches the tools the agent actually needs — the MCP surface never advertises a tool the presented credential cannot execute.

What Agent Memory is not

It is not "Hyphae as another database." The product is the five-verb experience working identically across agents from one hyphae agent setup, reversible without data loss, and verifiable without trust — a recall's prove parameter returns a sealed proof, witness, and anchor a third party verifies offline (see Transactions and proofs). The engine underneath is an implementation detail nobody has to administer directly.