# 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](DESIGN.md).

## Quickstart

```sh
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`).

## Starfield renderer

```sh
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](DESIGN.md).