Shared memory. Plain files. No hosted service.
CLI agents can share one local Markdown vault and one validated write path. Claude Code supports automatic session hooks; other agents load a bounded packet explicitly at session start. The process-ancestry gate is an access guardrail, not a filesystem sandbox.
Using an AI agent? Read the machine-readable guide: memory.bridges.community/agents.md
Why agent memory usually fails
- Many tools keep separate memory silos — ChatGPT memory, CLAUDE.md, Cursor rules — with no shared local canon.
- Pull-model dependence: an agent has to remember to query memory before it can use it.
- Context compaction can drop session-only knowledge that was never checkpointed.
- A plain local vault remains readable to processes with equivalent filesystem permissions.
Structure built around one canon
- One shared vault for integrated agents — runtime-specific memories can remain session caches.
- Explicit integration — Claude Code can use a session hook; other agents run
spine-packetat session start. - Checkpoint discipline — record at milestones, pins for env-facts, post-compaction recovery.
- Spine-mediated access guardrail keyed on process ancestry, with an owner-managed allowlist and audit log.
This is what agent memory looks like
The vault opens in Obsidian as a graph: every dot is one Markdown record, every cluster a project scope around its hub, every edge a wikilink. Shown as an example graph; no private vault records are included in the repository.
The memory cycle
Write at checkpoints
Agents record decisions and facts the moment they happen — through spine-new only: validation, secret scan, dedup gate.
One append-oriented canon
One record = one Markdown file in ~/AgentMemory. The protocol supersedes rather than edits records; spine-sync can commit on an owner-configured schedule.
Distill honestly
Each scope compiles into a bounded packet with a 14 KB default and an optional per-scope cap: pins first, then mutually exclusive blocker, thread, decision, and fact groups. Every truncation carries an honest counter.
Integrate per agent
Claude Code can receive the packet through a hook. Other agents load it explicitly; no universal auto-injection is claimed.
Design decisions encoded in tools and tests
Files with local git history
Local history and audit come from git; backups work only after you configure and verify them. The protocol supersedes records rather than silently erasing them.
Secret references, not values
Memory policy stores only "name + where it lives". A lightweight scanner checks each record; gitleaks adds pre-commit and CI defense in depth.
A lifecycle for knowledge
Inbox for topics with no home, owner triage, a candidate-promotion workflow, and pins for environment truths.
Explicit access guardrail
Spine-mediated access now checks identified callers against a process-ancestry allowlist. The allowlist is owner-managed by policy; filesystem permissions remain the enforcement boundary.
Injection-aware framing
Packets are framed as data, not instructions. Untrusted records are excluded from generated packets.
Operations toolkit
Sync, backup, health and digest tools; a dead-letter queue; an 18-test selftest; starvation alarms; atomic writes.
Against the usual approaches
| Instead of | Memory Spine |
|---|---|
| Per-tool memory silos with opaque retention | One canon for each integrated agent; runtime-specific memories can remain session caches. |
| A vector DB or memory service holding your data | Files + git, local. A public 12-case synthetic regression set documents current keyword-recall behavior; it is not an external benchmark. |
| Hoping the agent remembers to ask | Automatic for configured Claude hooks; explicit session bootstrap for other agents. |
| Notes dumped into the context window | Typed, size-bounded distillation with confidence levels and honest counters. |
| Trusting every process using the tools | Process-ancestry guardrail for Spine commands plus an audit log; OS permissions still control direct file access. |
Questions that come up first
Is this a database or a framework?
Neither. It is plain Markdown files in a local git repo plus bash/Python CLI tools. A shell-capable agent can participate once explicitly integrated; no SDK, memory server, or product account is required.
What stops a random app from reading my memory?
Spine tools check identified callers against a process-ancestry allowlist and log their decisions. This guardrail covers Spine-mediated access, not direct filesystem reads. The vault remains a plain folder, so filesystem permissions and keeping secret values out of memory remain the underlying boundaries.
Why not embeddings and vector search?
The repository includes a 12-case synthetic top-1 regression set for keyword search with morphology and synonyms. It currently passes 12/12 locally. This is a transparent regression check, not an independent comparison with vector search.
Does it work outside macOS?
The installer and core selftest run in a macOS + Linux CI matrix. macOS includes launchd templates and optional Keychain support; Linux scheduling still requires an explicit cron or systemd setup.
How does it survive context compaction?
By design: agents write at checkpoints, environment facts can be pinned, and packets include a per-agent delta. Claude Code hooks can re-inject after compaction; other runtimes must call the packet command explicitly.
What about backups?
Backup behavior is opt-in. After the owner installs a scheduler, spine-sync can update a same-machine bare mirror; a separately configured backup job can copy to an external volume, and spine-health can report staleness. None of these jobs runs merely because the core installer completed.
Give your agents a memory that survives the night
https://github.com/AlexBridgesman/memory-spine
Reproduce the evidence locally: the isolated installer test runs selftest 18/18, config-preservation and uninstall contracts; the public recall set reports its own top-1 result.