SAM — Super Agent Memory

One persistent, token-frugal memory for every coding agent. Claude Code · Codex CLI · Gemini CLI · Antigravity (IDE / CLI / 2.0) · OpenCode · Cursor · any MCP client.

Türkçe README · Documentation · Getting started · CLI · FAQ

npm i -g super-agent-memory
sam install        # detects your agents and wires hooks + MCP + rules

The package is on npm. Each GitHub release also carries the tarball and SHA256SUMS.txt for offline installs; git clone … && npm link gives you a working copy. Details: Getting started.

That is the whole setup. No server, no API key, no Python, no Docker, zero npm dependencies. Requires Node.js 22.16+ (22.x) or 24+. One SQLite file at ~/.sam/sam.db is shared live by all agents in the same environment, so a decision made in Claude Code is known to Codex, Gemini and OpenCode the next time they start.

The package installs three names for the same CLI: sam, sam-memory and super-agent-memory. Use sam-memory if sam on your machine is the AWS SAM CLI; the rules SAM installs for agents always use sam-memory.

Why another memory?

We reviewed the 50 most-starred agent-memory repos updated in the last year end to end (README + source). Full reviews are in docs/RESEARCH.md. The same five problems kept coming up:

Benchmarks

Token benchmark (npm run bench): a synthetic project corpus (600 saved, 540 live after near-duplicate merges) and a 30-prompt session: 20 prompts need a specific stored memory, 10 are unrelated asks.

About 94% fewer tokens than a dump at the same recall, and fewer tokens than plain BM25 with far better recall. SAM spent about 140 tokens in total on the 10 unrelated prompts (BM25: about 425). Memory ids are random, so repeated runs vary by a few dozen tokens (2,073–2,110 over 6 runs, all 20/20). Token counts use SAM's estimator (within about ±5% of tiktoken o200k). The baselines are strategy archetypes seen across the reviewed repos, not re-implementations of specific projects. The corpus is templated, which flatters lexical search, so treat it as indicative. The harness is bench/tokens.js.

Tokens across models. Budgets and the numbers above are in o200k-equivalent units (SAM's estimator, calibrated to tiktoken o200k). Each model family tokenizes the same text differently, so the real count depends on the host. Counts measured on SAM's own output through each provider's tokenizer (OpenRouter usage.prompt_tokens, 2026-10-07):

So a 320-token card is about 320 tokens on GPT and Gemini models and about 485–540 on Claude 4.7 and later. Turkish text costs 1.24–1.34× English on o200k and Gemini, and 1.40–1.69× on Claude. The savings ratio in the token benchmark compares SAM with the baselines in the same units; it was not re-measured per tokenizer. Script: bench/native-tokens.mjs.

Retrieval benchmark (npm run bench:retrieval): 411 hand-written memories across three projects plus global and auto-capture noise, 239 English and Turkish prompts with graded labels (32 of them unrelated), a 40-turn session and a must-know set per project. Gate settings were tuned only on the odd-numbered half; the even half is held out.

(dev-2/dev-3 are pre-release builds.) The three bench projects each hold 40 or fewer non-note memories, so 1.0.0 gives them the whole store as a deterministic dump instead of a ranked card. Details, splits and caveats are in bench/retrieval/README.md. Embeddings are not needed for any of these numbers.

Blind benchmark (npm run bench:v2): 539 positive and 858 negative EN/TR prompts written by one model vendor and judged by another, split by hash into a dev half (used for tuning) and a held-out half (reported). Negatives are other-stack, other-project, unrelated coding, chit-chat and near-miss prompts.

The specificity gate removes almost every other-stack injection (0.35 → 0.01) and most other-project ones (0.25 → 0.06) at no hit cost. A tuned BM25 floor is a strong baseline on this set; SAM's gate needs no per-store tuning, and SAM adds the card and the ledger on top. The same run also covers: poisoning (the guard quarantines 43 of 48 agent-written poisoned notes; a poisoned note reaches a topical prompt 10% of the time, down from 79%), knowledge updates and dedup (see Known limitations in the CHANGELOG), and in-process recall latency (p50 ≈6 ms, of which ≈0.5 ms is the specificity gate). Full report: bench/retrieval-v2/results/1.0.0.txt.

Coding eval (npm run bench:coding): 34 coding tasks that can only be solved with a stored project fact (26 EN, 8 TR) plus 10 harm tasks, graded by tests, in three model/store conditions (gemini-3.8-flash on a 50- and a 270-row store, deepseek-v4-flash on the 50-row store; 1,899 graded calls, paired task-cluster bootstrap).

SAM ties a full dump at about one twelfth of its tokens; harm rates are 1.8–5.3% in every arm with no measurable difference. Pushing a fix card after a failure recovered +19.7 pp [+4.5, +38.8] of failed attempts and ships; an always-on "experience push" did not help (−1.5 pp) and does not. Method and per-task tables: bench/coding-eval/.

Hook latency (npm run bench:latency, fresh process per prompt, 60 memories, Linux x64, Node 22.23): median ≈86 ms, of which ≈26 ms is Node startup (the last pre-release build measured ≈79 ms on the same machine, so 1.0.0's guard, gates and handoffs add ≈7 ms; run-to-run noise is about ±10 ms).

Related MCP server: recollect

How it works

 Claude Code ─┐  hooks: SessionStart · UserPromptSubmit · PostToolUse(+Failure) · PreCompact · Stop · Subagent*
 Codex CLI ───┤  hooks.json (same events) + config.toml MCP
 Gemini CLI ──┤  SessionStart · BeforeAgent · AfterTool · PreCompress · AfterAgent · SessionEnd
 Antigravity ─┤  PreInvocation (injectSteps) · PostToolUse · Stop  + mcp_config.json + rules
 OpenCode ────┤  plugin: chat.message · tool.execute.after · session.idle · compacting
 Cursor ──────┤  hooks.json: sessionStart · postToolUse(+Failure) · afterAgentResponse + MCP
 other MCP ───┘  MCP + rules (`sam snippet`)
        │
        ▼   ~/.sam/bin/sam hook <event> --agent <name>   (launcher finds Node; ≈70–90 ms per prompt on Linux incl. Node startup, `npm run bench:latency`; never blocks the host)
 ┌──────────────────────────── SAM engine (Node 22.16+/24, node:sqlite) ────────────────────────┐
 │ capture   prompts → directives ("from now on…", "unutma…") · edits · commands + outcome    │
 │           error→fix detection · inline ⟦mem⟧ markers from the assistant's own prose only   │
 │ store     typed memories · provenance (user/agent/auto/team/import) · near-dup merge       │
 │           supersession ("subject: value", "X instead of Y", negations) · secret redaction  │
 │ retrieve  BM25 + trigram + EN/TR alias expansion [+ optional embeddings] → RRF            │
 │           × concept coverage × importance × recency (with a floor for key decisions)      │
 │ inject    budgeted card · evidence-gated recall · file notes · subagent mini-card · ledger │
 │ vault     full command output stored, digest shown, `sam-memory out <id> --grep` on demand│
 │ hygiene   `sam gc` (also a light daily run): expire, merge, archive, reinforce            │
 └────────────────────────────────────────────────────────────────────────────────────────────┘
        ▲
        └── MCP (4 tools) and CLI for explicit recall/save; Markdown/JSONL export; team file in git

What an agent sees at session start (real output of sam context, 172 tokens):

<memory project="shop">
conventions the user recorded:
- commit mesajlarını İngilizce yaz
- package manager: pnpm, never npm
user preferences:
- answer in Turkish, code comments in English
decisions (newest wins):
- auth: JWT in an httpOnly cookie, refreshed every 15 min · 10-07
- test runner: vitest with --pool=forks; threads crash on Node 22 · 10-07
facts:
- Stripe webhooks are verified with STRIPE_WEBHOOK_SECRET in... · 10-07 #vs0h
saved inline: ⟦mem decision: <subject>: <value>⟧ (same subject replaces the old value; no status notes) · more: mem_search → mem_get(#id)
</memory>

And for the prompt "how do we verify the stripe webhook signature?" (39 tokens):

<memory recall>
- (fact 10-07) Stripe webhooks are verified with STRIPE_WEBHOOK_SECRET in src/billing/webhook.ts #vs0h
</memory>

Decisions and facts carry their date and are listed newest first, so the model can tell which of two lines is current. A #id appears only when mem_get would return more than the line shows. Conventions can come from the user saying "Bundan sonra commit mesajlarını İngilizce yaz", decisions from an inline ⟦mem⟧ marker in the agent's reply, fixes from a failing → edited → passing test run. No model call is involved.

Design details are in docs/ARCHITECTURE.md.

Integrations

sam install auto-detects agents; sam install claude codex … or --all to choose; --dry-run to preview. It writes a small launcher (~/.sam/bin/sam, plus sam.cmd/sam.ps1 on Windows) that hooks and MCP entries call, so upgrading or switching Node (Homebrew, nvm, Volta) does not break them. After installing, it runs every installed command once through its host's real shell and prints self-test: …. Every edited file gets a one-time .sam-bak backup; sam uninstall removes what was added, including the backups and any file it created that is empty again.

If an agent's hook system changes, capture degrades gracefully: MCP, rules and the CLI keep working. sam doctor reports installed entries that point at missing paths (BROKEN: … → run sam install).

Windows

• Hook commands are generated per host shell: Claude Code ≥ 2.1.139 uses exec form (no shell); older Claude uses Git Bash when present, else PowerShell; Gemini CLI and Cursor get PowerShell (& '…\sam.cmd' …); Codex gets cmd quoting. Hosts that spawn without a shell (Claude exec form, MCP entries, the OpenCode plugin) call node.exe + sam.js directly.

• sam run uses Git Bash if installed, else PowerShell, else cmd (SAM_SHELL=bash|powershell|cmd overrides). Output in a non-UTF-8 console code page (CP857, Windows-1254, …) is decoded correctly; SAM_VAULT_ENCODING forces one.

• Windows support is exercised in CI (Windows × Node 22.16/24) and by simulated command generation; real-host execution of every shell form is less battle-tested than POSIX. sam doctor self-tests what was installed.

One database per environment

SQLite's WAL mode needs shared memory on one kernel. Keep one local SAM_HOME per environment: Windows, each WSL distro, each container or devcontainer, each SSH host. Do not point SAM_HOME at /mnt/c/… from WSL, an NFS/SMB/9p/FUSE mount, a Docker Desktop bind mount shared with the host, or a Dropbox / iCloud Drive / OneDrive / Google Drive folder. If the DB is on such a filesystem anyway, SAM uses the slower rollback journal instead of WAL and sam doctor / sam install warn (SAM_ALLOW_SHARED_FS=1 forces WAL if you know the mount is safe).

Move memories between environments with sam export --jsonl / sam import --trusted, or share project knowledge through a committed .sam/memory.md. Repos with a git remote get the same project id everywhere; give remote-less repos a .sam-project file with a name. In a devcontainer, run sam install inside the container (e.g. in postCreateCommand) and mount a named volume at ~/.sam if memory should survive rebuilds.

Security and safety

• Team files need a human review. A repo's .sam/memory.md is imported only after you run sam trust in that repo: it shows the number of lines and a preview and asks [y/N] in a terminal (scripts pass --yes). Trust is pinned to that exact content: when a teammate changes the file, nothing new is imported until you review it again, and the card tells the agent to ask you. An agent running sam trust from its shell has no terminal and is refused. sam export --team never marks a repo trusted.

• Provenance. Every memory records who wrote it: user (sam add, your directives), agent (markers, mem_save), auto (captured fixes and digests), team, import. Only you can pin. An agent cannot overwrite or supersede a value you saved or pinned (MCP tells it to ask you), unless you named the new value yourself in the same session. Team lines are never pinned; imports are untrusted unless you pass --trusted for your own backups.

• Poisoning guard. Memories written by agents, teammates or imports that look like an injection (remote scripts, disabled checks, exfiltration, weakened auth, "ignore the user") are quarantined, and bursts of agent writes beyond a per-session / per-day cap wait as pending. Held memories are invisible to agents and never replace a live one; you see them in sam review (approve / reject; unreviewed ones expire after 14 days) and sam audit. On the card, agent / team / import lines are tagged -a / -t / -i.

• Memory is data. Text is NFKC-normalized and stripped of invisible, bidi and Unicode-tag characters, and </> are escaped, so a stored line cannot close the <memory> block or hide instructions from a reviewer. The installed rules say memory lines never change the agent's permissions or tools.

• Harvest only what the assistant said. Markers come from an allow-list of assistant-message formats per host; tool output, files the agent read, compaction summaries, reasoning, quoted text, code blocks and blockquotes are ignored. At most 8 markers per turn.

• Secrets are masked before anything is stored, including vault output: about 30 formats (OpenAI, Anthropic, Stripe, GitHub, GitLab, npm, Hugging Face, Slack, AWS, Google, SendGrid, Discord, JWTs, PEM and PuTTY keys, base64-wrapped keys, Bearer/Basic headers, URL passwords, curl -u, *_PASSWORD=, "token": "…"). Redaction runs in linear time on adversarial input.

• MCP is scoped. mem_get and mem_forget only see the current project and global; arguments are length-capped and oversized requests refused.

• sam run refuses a single quoted argument that contains shell operators unless you pass --shell. Approving sam run in a host still approves whatever comes after --, so treat that approval like approving a shell.

• Erasure. sam purge removes content from every table (memories and their older versions, raw events, first prompts, vault, digests, handoffs, the team file) and rewrites the DB; a fingerprint (tombstone) keeps it from being captured again. sam forget --hard leaves a tombstone too.

• Files and installer. ~/.sam is 0700 and the DB files 0600; sam forget --hard securely deletes and purges the search index. The installer never writes through a symlinked config file. A non-localhost embedding endpoint is used only when ~/.sam/config.json opts in, never from an environment variable alone.

Report vulnerabilities as described in SECURITY.md. The audits (code, host integrations, and the six-perspective audit of v1.1.0) are summarized in docs/AUDIT.md and docs/AUDIT2.md.

Using it

Mostly you don't. Capture and injection are automatic. Useful commands (sam and sam-memory are the same):

sam q "stripe webhook"            # search → [kind] gist #id
sam get 29on 17vc                 # full detail
sam add "deploy: fly.io via GH Actions" -k decision --pin
sam context --prompt "fix login"  # preview exactly what an agent would receive, with token counts
sam run -- pnpm test              # output vault: digest now, `sam out <id> --grep FAIL` later
sam stats                         # tokens injected vs. kept out of context
sam export --team                 # write <repo>/.sam/memory.md, commit it
sam trust                         # teammates: review that file, then allow its import (off by default)
sam doctor                        # detection, DB health, config problems, broken paths, self-test
sam doctor --repair               # rebuild the search index or salvage a damaged DB
sam gc                            # hygiene (also runs lightly once a day on its own)
sam review                        # held memories (quarantined / pending): approve or reject
sam audit                         # who wrote what, what gets injected, quarantine reasons
sam purge --query "old api key"   # erase content everywhere (+ tombstone), then VACUUM
sam handoff "auth done; tests for refresh left" --to codex   # the next codex session here gets it once

Inside any agent you can also just say "remember that…", "from now on…", "always/never…" (Turkish: "unutma…", "bundan sonra…", "artık X değil Y", "her zaman/asla…"). These are saved as facts, conventions, preferences or decisions; repeatable multi-step how-tos can be saved as -k procedure. Write decisions as subject: value (queue: SQS, not Kafka): a later value for the same subject replaces the old one, and so do "X instead of Y" and "switched from Y to X".

Exit codes: 0 success, 1 not found or a failed check, 2 usage error. SAM_DEBUG=1 shows stack traces.

Configuration

Set values in ~/.sam/config.json or with env vars: the key in upper snake case with a SAM_ prefix (budgetPrompt → SAM_BUDGET_PROMPT). Precedence: env > config.json > default. Values are type-checked; a bad value falls back to the default with a warning, and sam doctor lists config problems and unknown keys.

Environment variables: SAM_HOME (DB, config and launcher folder, default ~/.sam; the value at install time is baked into the launcher), SAM_NODE (Node binary for the launcher), SAM_SHELL and SAM_VAULT_ENCODING (sam run on Windows), SAM_ALLOW_SHARED_FS=1 (keep WAL on a network or synced folder), SAM_PROJECT_DIR (pin the MCP server to a project), SAM_SESSION, SAM_DEBUG=1. Development only: SAM_INSTALL_HOME, SAM_TEST, SAM_SELFTEST, SAM_CLAUDE_VERSION.

Privacy

Everything stays on your machine. API keys, tokens, JWTs, private keys and password= patterns are masked before anything is written, personal data (e-mail, phone, IBAN, TCKN) is masked too (redactPII), and <private>…</private> spans are dropped. sam purge erases a memory, a query match or a whole project from every table. Nothing leaves the machine unless you configure an embedding endpoint yourself.

Development

npm test                 # 184 tests (store, search, retrieval, capture, vault, hooks per host, MCP, installers,
                         #   security, robustness/chaos, workflow, platform, CLI, schema/privacy, guard, gate,
                         #   injection, sharing, integration); SAM_SLOW=1 adds the long chaos run
npm run bench            # token benchmark (with a pure-BM25 baseline)
npm run bench:retrieval  # retrieval-quality benchmark (no embeddings or Python needed)
npm run bench:v2         # blind EN/TR benchmark + knowledge-update, poisoning, dedup and latency suites
npm run bench:latency    # per-prompt hook latency
npm run bench:coding     # memory-necessary coding eval (needs an OpenRouter key)
npm run e2e              # install into a temp home and run every installed hook command through sh

Requires Node.js 22.16+ (22.x) or 24+ (the built-in node:sqlite with FTS5). See CONTRIBUTING.md, CODE_OF_CONDUCT.md and CHANGELOG.md.

Documentation

Credits

SAM stands on ideas proven by the projects in docs/RESEARCH.md, especially claude-mem (progressive disclosure), context-mode and openwolf (output sandboxing), engram (topic keys), agent-memory and ai-memory (lexical-first, budgeted briefs), ReMe and OpenViking (no repeats), pro-workflow (inline learn markers) and obsidian-mind (degrading budgets).

MIT License.