From 0e240ee45396ca8984d533696b70e1541cf9185b Mon Sep 17 00:00:00 2001 From: vreshch Date: Sat, 27 Jun 2026 00:12:42 +0200 Subject: [PATCH] docs: add agent-facing CLAUDE.md --- CLAUDE.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4ab90d5 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,23 @@ +# @agentage/server-memory — CLAUDE.md + +The stdio **MCP server** for agentage Memory: exposes local vaults as the frozen 6 +`memory__*` tools. Deliberately **tiny** — just the MCP definition. All memory logic +(backends, git, search, routing) lives in `@agentage/memory-core`; don't add it here. + +## Layout (src/) +- `server/memory-tools.schema.ts` + `.mcpc.json` — the **frozen 6-tool contract** (Zod source + CI snapshot). +- `server/register-tools.ts` — wires the schema to memory-core's router. +- `server/render-markdown.ts` — the text channel renderer (pure; list=outline, read=raw doc). +- `server/create-memory-server.ts` — `createMemoryServer(registry, opts)`, transport-agnostic. +- `server/local-server.ts` — `loadLocalServer()` (reads `~/.agentage/vaults.json`). +- `bin/server-memory.ts` — ~15-line stdio entry. + +## Rules +- The 6-tool `memory__*` contract is **frozen**. Schema + `.mcpc.json` must stay in sync. +- `.mcpc.json` is a CI snapshot (`z.toJSONSchema`, draft-2020-12) — it disagrees with the live `tools/list` (SDK, draft-07). **Verify contract claims against a dumped live `tools/list`, never the snapshot** — snapshot-only checks go false-green. +- Descriptions flow to BOTH serializers — the safe cross-model lever (the model routes on the description, not just the schema). +- Transport-agnostic by design: stdio bin here; the CLI daemon reuses `createMemoryServer` over Streamable HTTP. Keep it that way. +- `@agentage/memory-core` is a `file:` link until both publish — build core first (the e2e does this automatically). + +## Verify +`npm run verify` (type-check + lint + format:check + test + build). Tests: contract (tools/list = 6) + tools (in-memory) + e2e (init → spawned bin → round-trip).