coord-mem

A memory-palace graph for AI agent memory — zero-dependency Node, with a CLI, an MCP server, and a live starfield renderer.

Memories are append-only nodes rooted at an origin. Each records:

• Provenance — the context set: ids of every memory present when the thought formed. Multi-parent, captured at creation, immutable forever.

• Placement — one chosen home (the shelf where you'd look for it), making the graph walkable as a tree from the origin. Mutable via rehome.

• Coordinate — a stored (x, y, z) lattice address, auto-assigned to the nearest free slot beside its home. Stable, citable, never contested; moves only with rehome.

Two live signals grow on top:

• Brightness — decayed warmth from use plus rare, heavily-weighted likes. Decides retrieval rank and render glow.

• Adjacency — never declared; derived as PMI over recorded context windows ("these two memories appear together more than their popularity predicts"). Feeds neighbor queries, retrieval expansion, room clustering, and mis-shelving detection — a memory whose co-travelers live far from its shelf gets flagged with a suggested re-home.

Address vs. affinity is the core design split: the coordinate is where a memory lives; PMI is how it's used. Their disagreement is signal.

Everything decays (default half-life 30 days), the store is append-only (supersede, never delete), and the core is deterministic (injectable clock, no randomness). The full argument for every decision — including the non-goals — is in DESIGN.md.

Quickstart

npm test                      # zero deps, Node >= 22, built-in test runner

node bin/coord-mem.js init "My project's core principles"
node bin/coord-mem.js add "Decision X because Y" --tags decision
node bin/coord-mem.js add "Refinement of that" --home n1 --context n1
node bin/coord-mem.js walk
node bin/coord-mem.js retrieve decision

Store path via --file <path> or COORD_MEM_PATH (default ./coord-mem.json).

Related MCP server: ShelbyMCP

Starfield renderer

npm run view                  # http://localhost:4444

Self-contained canvas app, polls live. Palace mode pins each star at its stored coordinate — a stable map you can memorize. Gravity mode lets PMI springs pull co-used memories together — the usage clusters. Glow is brightness; cyan threads are co-occurrence; red rings are mis-shelved.

Claude Code integration

This repo dogfoods itself as live memory for agent sessions:

• .mcp.json registers bin/mcp-server.js (hand-rolled stdio JSON-RPC, still zero-dep) exposing memory_add / get / like / record_window / walk / retrieve / neighbors / rooms / misshelved / rehome.

• A Stop hook (bin/record-window-hook.js) scans each turn's transcript for memory tool activity and records one context window over every memory touched — so merely using memories maintains brightness and adjacency, hands-free.

• CLAUDE.md instructs sessions to author memories routinely but selectively: store decisions-with-why, reversals, and hard-won constraints; never activity logs. The bar: would a cold future session act differently for having read this?

palace.json is this repo's own live palace — the project's design history, recorded as it happened.

Origin

The model began as a question: would a spatial, origin-rooted social graph (posts as stars, tips as brightness) work as agent memory? What survived the design argument: append-only permanence, origin-rooted traceability, use-driven brightness, stored addresses. What didn't: typed faces, contested coordinates, single-parent provenance, deletion. See DESIGN.md.