distributed-ai-memory-system: Instructions file for Claude Code

Instructions for Claude Code working in this repo

Repo layout

npm workspaces monorepo, two workspaces under one root package.json: server/ (the Cloudflare Worker — Hono, D1, R2, MCP, token auth) and client/ (the Vite/React frontend, built into client/dist and served by the Worker as static assets). Run npm install once from the repo root. Root-level npm run <script> commands delegate to the right workspace — see "Commands" below. wrangler.toml and its CLI (wrangler d1 ..., wrangler secret put ...) live in and must run from server/. wrangler.toml is git-ignored on purpose (only wrangler.toml.example is tracked) so a fork of this repo can't accidentally deploy onto the original account's D1 database or domain — server/scripts/render-wrangler-toml.sh reconstructs a real one from the template at CI build time; see docs/DEPLOY.md's "Continuous deployment" section. The template's [ai]/[[vectorize]] bindings sit between # >>> semantic-search / # <<< semantic-search markers so CI can strip them (WRANGLER_DISABLE_SEMANTIC_SEARCH=1) — keep the markers when editing it.

Hard preferences (non-negotiable, apply repo-wide)

• npm only — never yarn or pnpm
• No Express, no Next.js
• No any in TypeScript — if a type is genuinely unknown, use unknown and narrow it
• Zod validation at every route boundary — no unvalidated c.req.json()
• Every backend module follows the 4-file pattern: schema.ts (Zod + types), service.ts (business logic, D1/R2 access), routes.ts (Hono handlers), index.ts (barrel export). Don't collapse these into one file even for small modules.
• Shared Bindings/Env type lives in server/src/lib/bindings.ts — modules import from there, they don't declare their own.

Data model rules

• R2 is the source of truth for memory content. D1 is an index/registry only — it should never hold data that isn't reconstructable from R2.
• memory.jsonl is append-only. Never rewrite history in place; the sync model (local CLI ↔ R2) depends on this being true. If you need to "edit" an entry, append a new one and treat resolution as an application-level concern, not a storage-level overwrite.
• Memory entries have a type of entity, relation, or observation. The frontend graph (client/src/components/MemoryGraph.tsx) assumes entity entries carry a name and relation entries carry source/target matching entity names — if you change entry shapes, update that assumption or the graph silently renders nothing.
• Content shape conventions by type (documented, not Zod-enforced — see memoryEntrySchema in server/src/modules/projects/schema.ts — enforcing them strictly would reject entries written before the convention existed):
  • entity: { name, category? }. category is one of entityCategorySchema's ten values; readers default to "other" (DEFAULT_ENTITY_CATEGORY) when it's absent. Old entities predate this field — that's expected, not a bug to backfill automatically.
  • observation: { text, entity? }. text is the plain-language note; entity optionally names which entity (by name) it's about — absent means a general project note, not an error. Entries that predate this shape (no text string) fall back to a JSON preview in the UI rather than breaking.
  • relation: { source, target, label? } — unchanged.
• Entities are last-write-wins, not append-once. An entity can be appended again under the same name; the append-only log keeps every revision (the raw R2 file and read_memory still return all of them — never filtered), but any reader building a "current" view (the frontend graph/entries table, update_entity) should dedupe by content.name and keep the last occurrence in file order. The canonical implementation is currentEntities(), duplicated in server/src/modules/projects/service.ts (backend) and client/src/lib/memory.ts (frontend, which doesn't build against the Worker's source tree) — keep both in sync if the rule changes. Relations and observations are never deduped; every one is part of the log.
• update_entity (MCP tool, server/src/modules/mcp) is how a category (or any other entity field) gets attached after the fact: it appends a new entity revision merging the given fields onto the entity's current content. It fails clearly if no entity with that name exists yet — creating one is still append_memory's job.