agent-memory

Persistent, semantic long-term memory for AI agents — so an agent stops being amnesiac. It remembers decisions, gotchas, conventions, and preferences across sessions, and recalls the relevant ones automatically on every prompt.

remember("This machine has no Node by default — run `export PATH=…nvm…` first", type: "gotcha")
        ↓  (a later session, different task)
user: "node: command not found"
        ↓  a hook silently injects:
## Relevant memories (from agent-memory)
- [gotcha] This machine has no Node by default — run `export PATH=…nvm…` first

The agent fixes it instantly — because last time's lesson was waiting for it.

The hard part: getting agents to actually use it

A memory tool nobody calls is dead weight. So adoption isn't left to chance:

• Recall is automatic (push, not pull). A Claude Code UserPromptSubmit hook runs agent-memory recall "<prompt>" and injects the result into context on every turn. The agent never has to decide to recall — relevant past knowledge is just there. A relevance floor means it injects nothing when nothing matches, so it never pollutes context.
• Writing is nudged. The MCP tool descriptions tell the agent when to remember, a low-friction reflect tool saves several learnings in one call at the end of a task, and agent-memory instructions prints a CLAUDE.md snippet that makes "save durable learnings" a standing instruction in the agent's context.

This is the same pattern Claude Code's own memory uses (auto-loaded MEMORY.md + instructions) — just semantic, ranked, scoped, and self-correcting.

The memory model

Each memory has a type — decision · fact · gotcha · convention · preference · task · reference — and a scope (global, or a project id). Recall returns the current project's memories plus global ones. Memories also have:

• relevance × recency × usefulness ranking — fresh and frequently-recalled memories rise; stale ones fade.
• dedup on write — a near-identical memory updates in place instead of piling up.
• supersession — a new memory can replace an outdated one (supersedes), and superseded memories stop being recalled (so memory self-corrects instead of rotting).
• links — memories can reference each other, forming a small knowledge graph.

MCP tools

remember, recall, forget, prune, link_memories, list_memories, memory_status. prune is long-term hygiene — it drops superseded and stale, never-recalled memories so the store stays useful over months.

Recall quality (measured)

npm run eval runs a labeled corpus + query set and reports hit@1 / hit@3 / MRR plus how often off-topic queries correctly stay below the relevance floor — so ranking changes are measured, not eyeballed. Current baseline (local MiniLM):

| metric | value | |--------|-------| | hit@1 | 41% | | hit@3 | 76% | | MRR | 0.56 | | off-topic held below floor | 3/3 |

So the right memory is in the top 3 most of the time, and the floor (0.35) is calibrated: off-topic queries inject nothing. The remaining misses are synonym gaps the small embedding model doesn't bridge (the model is the ceiling, not the ranking) — a code-tuned or larger embedder would lift it.

Setup

npm install      # needs Node 22+ (built-in node:sqlite); first run downloads a ~90MB embedding model
npm test

Register the server + the auto-recall hook

# 1. the MCP server (gives the agent the remember/recall tools)
claude mcp add agent-memory -- node /abs/path/agent-memory/dist/server.js

# 2. the hook that auto-recalls on every prompt — print the config and add it to settings.json:
node /abs/path/agent-memory/dist/cli.js hook

By default memory lives in ~/.agent-memory/memory.db (one brain across all projects, scoped internally). Override with AGENT_MEMORY_DB / AGENT_MEMORY_SCOPE.

CLI

agent-memory remember "deploys go out via deploy.sh" --type convention
agent-memory recall "how do I deploy"      # prints injectable markdown (or nothing)
agent-memory list --type gotcha
agent-memory status

How it works

SQLite + sqlite-vec for storage and vector search; FTS5 for keyword search; local MiniLM embeddings (offline, nothing leaves the machine). Recall fuses vector + lexical results (reciprocal rank fusion) and re-weights by recency and access count. Same engine family as a code search index — pointed at agent-authored knowledge instead of code.

Honest limits

• Recall is the strong half; write-adoption is softer — it depends on the agent judging what's worth saving (nudged by tool descriptions + a Stop hook), and is the part to iterate on.
• Name/relevance based, not a reasoner — it retrieves; it doesn't verify a memory is still true (supersession is explicit, not automatic).
• In-memory model load per process; recall through the CLI pays a model-load cost (~seconds) per call — fine for a per-prompt hook, but batchable later.

Version note

Requires Node 22+ for the built-in node:sqlite. sqlite-vec ships prebuilt binaries (no native build step).