@dudoxx/ddx-memory-mcp

Perpetual memory for agent sessions — an MCP stdio server exposing the DDX PerpMemory gateway (:11200): typed, versioned, self-curating DDXMemoryCard objects with hybrid recall, ingest, and a five-pass reconcile engine (dedup / conflict / distill / reorg / reclaim).

This package is a thin typed proxy: it holds no business logic and no datastore. It presents the gateway's frozen surface as four dispatcher tools, four resources, and two prompts over MCP.

Install

npm install -g @dudoxx/ddx-memory-mcp     # global (or install per-project)
npx -y @dudoxx/ddx-memory-mcp             # one-off

Requires Node.js ≥ 20.19.

Configuration

The server needs a running PerpMemory gateway. Two env vars:

| Variable | Meaning | |---|---| | PERPMEM_SERVER_URL | Gateway base URL (default http://127.0.0.1:11200) | | PERPMEM_API_KEY | Shared bearer the gateway authenticates (fail-closed when absent) |

Env vars win; otherwise the process probes a .env.dudoxx next to the launch cwd. The gateway is the product — this package only proxies it. See dudoxx-perpetual-memory for the gateway, ddx-docker-infra/, and the ddx-mem CLI.

Register (Claude Code)

claude mcp add --scope user \
  ddx-perpmem \
  --env "PERPMEM_SERVER_URL=http://127.0.0.1:11200" \
  --env "PERPMEM_API_KEY=<your key>" \
  -- npx -y @dudoxx/ddx-memory-mcp

Other MCP hosts: register the ddx-perpmem-mcp binary (npx -y @dudoxx/ddx-memory-mcp) as a stdio server with the same env.

Surface

| Kind | Names | |---|---| | Tools | memory_recall (search live; get/timeline/neighbors/decks registered), memory_write (upsert live; append/link/pin/supersede/archive registered), memory_deck (list live; create/bind/unbind/resolve/explain registered), memory_curate (reconcile/dryrun/ingest/health live; report registered) | | Resources | ddxmem://index, ddxmem://doctrine, ddxmem://deck/{slug}, ddxmem://card/{id} — registered; content resolves as the gateway routes land | | Prompts | memory-load (recall guidance + ≤3 calls/turn cap), memory-audit (reconcile walkthrough) |

Ops marked registered return a legible "not yet live" error — the surface is frozen at the gateway's current routes; no schema change is needed when they land. Resident schema is ≤ 6,144 bytes by design (standing-context budget).

Development

npm install && npm run build   # tsc → dist
npm test                       # zod-repair suite
npm run test:smoke             # stdio smoke vs a live gateway

bin/ddx-perpmem-mcp runs dist/index.js when built, else tsx src/index.ts.

License

MIT — © 2026 Dudoxx UG (haftungsbeschränkt) / Acceleate Consulting. See LICENSE.