Super Agent Memory v1.0.2

Added

• MCP tool annotations: all four tools declare readOnlyHint, destructiveHint, idempotentHint and openWorldHint as explicit booleans (mem_search/mem_get read-only; mem_save additive, idempotent upsert; mem_forget destructive, idempotent; none open-world). Hosts can now gate writes and warn before mem_forget. The tool list grows by about 110 tokens (o200k, now about 380–420); the tools/list hash changes once, so hosts re-cache their prefix one time.
• README (EN/TR): M8ven score badge.

---

Install: npm i -g super-agent-memory (npm) and then sam install. Offline: npm i -g https://github.com/cumabozkurt/super-agent-memory/releases/download/v1.0.2/super-agent-memory-1.0.2.tgz. See the README and Getting started. SHA256SUMS.txt holds the tarball's checksum.

Super Agent Memory v1.0.1

First npm release: super-agent-memory is now on the npm registry, published from GitHub Actions with provenance. No code changes since 1.0.0.

Changed

• Install with npm i -g super-agent-memory. README (EN/TR), Getting started and FAQ updated; GitHub release tarballs stay available for offline or pinned installs.
• README badges: npm version.
• release.yml publishes to npm before creating the GitHub Release and skips a version that is already on npm, so a failed run can be re-run safely.

---

Install: npm i -g super-agent-memory (npm) and then sam install. Offline: npm i -g https://github.com/cumabozkurt/super-agent-memory/releases/download/v1.0.1/super-agent-memory-1.0.1.tgz. See the README and Getting started. SHA256SUMS.txt holds the tarball's checksum.

Super Agent Memory v1.0.0

First public release (GitHub release). SAM is one persistent, token-frugal memory shared by every coding agent on a machine (Claude Code, Codex CLI, Gemini CLI, Antigravity, OpenCode, Cursor, any MCP client): zero npm dependencies, one local SQLite file (node:sqlite, Node.js 22.16+ (22.x) or 24+), LLM-free capture. Earlier internal milestones (numbered 1.0.0–1.2.0 during development, never published) are summarized under Pre-release development notes in CHANGELOG.md.

Core

• Capture without a model call: user directives in English and Turkish ("remember…", "from now on…", "unutma…", "bundan sonra…", "artık X değil Y"), edits, commands and outcomes, error → fix pairs, inline ⟦mem kind: text⟧ markers (no tool call), rolling session digests, subagent harvest.
• Hybrid retrieval: BM25 (porter) + trigram + optional embeddings fused with RRF, re-weighted by importance, per-kind decay with a floor for durable kinds, pinning, project scope and coverage of rare query concepts; bilingual EN/TR alias table, Turkish suffix stripper, typo correction, identifier twins, temporal intent ("yesterday", "dün").
• Budgeted injection: a ≤320-token session card, relevance-gated per-prompt recall (≤160 tokens), file-anchored notes, ≤140-token subagent mini-cards, and a per-session ledger so nothing is paid for twice.
• Output vault (sam run, sam out), a 4-tool MCP server plus short MCP instructions, a CLI for every operation (sam-memory alias for machines where sam is the AWS SAM CLI), Markdown/JSONL export/import, a reviewed and content-pinned team file (.sam/memory.md, sam trust).
• Installers for all six hosts, with per-shell Windows hook commands, a stable launcher that survives Node upgrades, a real-shell self-test, .sam-bak backups and a clean sam uninstall.
• Robustness: corrupt-DB salvage (sam doctor --repair), read-only / full-disk tolerance, rollback journal on shared or synced filesystems, clock-jump clamping, a light daily gc, hook fast path with V8 compile cache.

Memory model and privacy

• Schema v3 (migrated automatically from v1/v2): status, valid_from / valid_to, tombstones, handoffs. A binary older than the DB opens it read-only instead of damaging it; sam doctor reports the newer schema.
• One live-row predicate (liveSql() in store.js) on every read path — search (IDF, candidate lists, session recall, specificity signature), card, small-store dump, file notes, fix push: not superseded, status = 'active', inside its validity window. sam q --include-quarantined adds held rows for the human only.
• procedure kind (tag R, long half-life) for repeatable multi-step how-tos, listed in mem_save, the installed rules and the skill text.
• Validity windows (sam add --valid-from/--valid-to): a fact can be scheduled or expire.
• Additive guard: "also", "ayrıca", "de ekle" add to a subject instead of replacing it. Two-stage dedup (SimHash candidate, then Jaccard + polarity/negation) in save and gc; held rows never merge or absorb.
• sam purge erases content from every table (memories and the versions they superseded, raw events, first prompts, vault, digests, handoffs, the team file), then VACUUM + WAL truncate; --include-backups also deletes sam.db.corrupt-* copies. Tombstones (exact + substring fingerprints, case/space/diacritic-robust) stop re-capture; sam forget --hard leaves one by default. saveMemory returns { id: null, status: 'tombstoned' } and every caller handles it.
• PII redaction (redactPII, on): e-mail, phone (TR / E.164), IBAN (mod-97), TCKN (checksum), on top of ~30 secret formats; RFC 2606/6761 reserved addresses (admin@shop.test, jane@example.com) stay readable.

Poisoning defense and review

• Guard (src/guard.js): non-user writes that match injection heuristics (remote scripts, disabling checks, exfiltration, weakening auth, "ignore the user"…) are quarantined; per-session and per-day caps on agent-written rows put the excess in pending. Held rows are invisible to agents (search, card, mem_get shows id + status only) and never retire or rewrite a live row. Tool-output taint marks writes that follow a suspicious tool result.
• sam review inbox (approve / reject / approve-all) with expiry (reviewExpireDays), sam audit (counts by source/status/kind, most injected, follow-up rate, quarantine reasons), optional reviewAgentRules.
• Source tags: agent / team / import lines carry -a / -t / -i bullets plus one legend line; user and auto lines keep -. Imported and team rows pass the guard too.

Injection

• Project-specificity gate (specGate): no per-prompt recall for prompts about a sibling project (naive-Bayes LLR over the projects in the DB) or a stack this project never uses. Held-out false injections 0.275 → 0.144 at unchanged hit.
• Native memory awareness: CLAUDE.md, AGENTS.md, GEMINI.md, rules files, Claude auto memory and Antigravity knowledge are read (never written); card lines the host already loads are dropped and contradictions noted once per session.
• Factual card wording ("conventions the user recorded", "how-to steps the user recorded", "saved inline: …"), no imperative out-of-band text; host output limits respected (fitContext, Claude Code 10,000 chars).
• Cache hygiene: card ranking in whole UTC days with id tie-breaks, read counters out of card ranking, a tools/list hash test.
• Small-store mode: a project with ≤40 live memories gets a deterministic full dump (≤1,500 tokens, ≤9,000 chars).
• Host-profiled budgets (budgetProfile, e.g. Claude 4.7+ ×1.6) and a ×1.25 budget for Turkish-heavy stores.
• Compact fix card + push after failure: after a failed command, the matching past fix is pushed once (≤2 per session, ≤70 tokens). The always-on "1-experience push" was measured and not shipped.
• Durable-line card cut: convention / decision / preference / procedure lines get 120 characters (cardGistMaxDurable) and a clause-boundary cut that never splits a code span, flag or quoted token (the coding eval showed --error-on-warnings, an ff- prefix and a timezone being cut at 80).

Sharing

• Agent-to-agent handoffs: written automatically at Stop / SessionEnd (and with sam handoff [--to agent] "<note>"), surfaced once (≤60 tokens) to the next session of another agent in the same repo; sam handoff --list.
• Portable skill with a CLI pull section for agents without MCP.
• Experimental, off by default: ACT-R activation as a ranking factor (actr, imported lazily so the prompt hook pays nothing while off), demotion instead of archiving (demote), sam sleep consolidation (sleep), skill drafts from repeated fixes (sam skills draft, never installed).
• gc prunes per-session and orphaned meta keys (fixpush:, needcard:, route:, tjson:, guard:, reinforced:, demoted:).

Benchmarks and evaluation

• npm run bench (token benchmark, now with a pure-BM25 baseline row), npm run bench:retrieval (411 memories, 239 EN/TR prompts), npm run bench:v2 (blind EN/TR set of 539 positives + 858 negatives written and judged by different vendors, dev / held-out split, knowledge-update, poisoning, dedup and latency suites, bootstrap CIs, BM25 baselines), npm run bench:latency, npm run bench:coding (memory-necessary coding eval, 34 pairs + 10 harm tasks), npm run e2e.
• Results at release: token bench ≈2,100 tokens at 20/20 recall vs 35,608 for a full dump (−94%) and ≈2,530 at 13/20 for pure BM25 top-3; retrieval v2 held-out hit 0.699 / false injections 0.144 (BM25 top-3: 0.903 / 0.935; BM25 with a dev-tuned floor: 0.741 / 0.124); guard quarantines 43 of 48 poisoned notes (topical injection 0.79 → 0.10); coding eval: SAM push + pull 93.1% vs no memory 16.7% vs full dump 94.6% at ≈1/12 of the dump's tokens.
• Test suite: 184 tests across 15 files, plus SAM_SLOW=1 chaos runs and a 36-command host e2e.

Fixed

• Held memories no longer leak to agents through three paths that skipped the status = 'active' check. These were quarantined rows and rows pending review:

  • the automatic handoff's open todos (src/handoff.js);
  • the session digest body, both its fixes and its saved items (src/capture.js);
  • the weekly digests written by sam sleep (src/sleep.js).

  The handoff query now also respects validity windows.

• JSONL backups keep validity windows. sam export --jsonl wrote valid_from / valid_to, but sam import dropped them, so a scheduled or expired fact came back as permanently live. Junk values and empty windows are ignored on import (src/portable.js).

• Exports hold only live rows. sam export (Markdown) and sam export --team now use the shared live-row predicate, so expired, not-yet-valid and held memories are no longer published to .sam/memory.md (src/portable.js).

• sam embed (src/embed.js, src/cli.js):

  • backfills only active memories, so held rows are never sent to an embedding endpoint;
  • no longer re-requests rows the endpoint returned no vector for;
  • stops when a batch returns nothing;
  • reports the number of vectors actually stored;
  • prints a clear hint and exits 1 when embeddings are not configured.

• sam doctor and sam stats count live memories only; doctor also shows how many are held for review (src/cli.js).

• sam out --tail N / mem_get no longer count the trailing newline of a captured output as an extra empty line (src/vault.js).

• File paths under a symlinked project root (macOS /var → /private/var, ~/code → another volume, Windows 8.3 short names such as RUNNER~1) stay project-relative when the file does not exist on disk, for exa...