ai-memory

> Turn AI editor chat history into typed Markdown + AGENTS.md rules — local-first, git-trackable, zero .remember() calls.

npx ai-memory-cli extract                     # read your editor's chat history → typed Markdown
npx ai-memory-cli rules --target agents-md    # → AGENTS.md (Cursor / Claude / Windsurf / Copilot / Codex all read it)
npx ai-memory-cli recall "OAuth"              # show the full git lineage of any decision
npx ai-memory-cli context --copy              # resume any session with full context

Every other "AI memory" tool starts with a remember() API and asks you to instrument your code. ai-memory reads your editor's chat history directly — Cursor, Claude Code, Windsurf, Copilot Chat, Codex CLI — and turns it into typed, git-trackable Markdown that every AI editor reads back via AGENTS.md. No new API surface to learn, no runtime memory store to keep alive between sessions.

Local-first by default. Conversations never leave your machine; the only network call is to whichever LLM provider you've configured for extraction. Or use Ollama / LM Studio for fully offline operation.

> 中文文档

---

What only ai-memory does

Four things you won't find together anywhere else. The first three are structural; the fourth is engineering investment nobody else is making.

1. Zero .remember() boilerplate. We read what you've already written — the Cursor / Claude Code / Windsurf / Copilot Chat / Codex CLI transcripts that already live on your disk. No SDK to import, no runtime memory store to keep alive. Compare with mem0 / Letta / Zep / cortexmem, which require client.add(...) calls from your application code.

2. Native AGENTS.md output. ai-memory rules --target agents-md writes the cross-tool standard rules file that Cursor, Claude Code, Windsurf, Copilot, and OpenAI Codex CLI all consume. The merge is idempotent: only the section between <!-- ai-memory:managed-section start --> ... end --> is touched; any hand-written content in your AGENTS.md is preserved byte-for-byte. AGENTS.md adoption crossed 60K repos and is now under Linux Foundation stewardship — most projects hand-write theirs from scratch; we generate it from your conversation history.

3. Plain Markdown in git — no database. .ai-memory/ is the source of truth: Markdown files you git diff, code-review, branch, and revert. Other tools that advertise "git-trackable" memory ship git-tracked snapshots of their internal store; we ship the human-readable file format and let git own everything. Cross-machine sync is git pull.

4. Time-travel recall via git history. ai-memory recall <query> shows the full commit-by-commit lineage of every memory: what the decision said on April 1, what it said on April 15, what changed and who changed it. Every other memory tool returns "the latest" only — superseded versions are silently overwritten. No new runtime dep: recall shells out to your existing git with a 10-second timeout.

We measure ourselves

CCEB — Cursor Conversation Extraction Benchmark, gpt-4o-mini, 30 hand-curated fixtures (v1.1 expansion):

| Metric | v1.1 (2026-04-27, 30 fixtures) | v1.0 / v2.5-01 (2026-04-26, 9 fixtures) | v2.4 (2026-04-25, 9 fixtures) |
|---|---|---|---|
| Overall F1 | 64.1% (P 56.8% / R 73.5%) | 76.2% (P 66.7% / R 88.9%) | 56.0% (P 43.8% / R 77.8%) |
| decision / issue F1 | 78.3% / 100% | 75.0% / 100% | 66.7% / 66.7% |
| architecture F1 | 72.7% (recall the new bottleneck) | 100% | 50% |
| Noise rejection (chit-chat / deferred / hypothetical) | 100% — no hallucinated memories on any of the 4 noise fixtures | 100% (2 fixtures) | 100% (2 fixtures) |
| Wall-clock | 239.7 s | 47.9 s | 70.5 s |
| Spend | ≈ \$0.02 | ≈ \$0.006 | ≈ \$0.005 |

The v1.1 expansion (cceb-001 — cceb-030) deliberately added harder cases v1.0 didn't exercise: multi-memory-per-conversation (architecture + convention together), commitment-shape ambiguity (process vs. technical TODOs), CJK/mixed-language conversations, and decision-impact-vs-followup-TODO triage. F1 dropped 12 pp from the 9-fixture row above; that's not a model regression — running the v1.0 fixtures alone against the same prompt still scores 76%. The 64% is the more honest measurement of the same extractor on a less cherry-picked fixture distribution. The biggest remaining lever is todo precision (11 of the 19 false positives are TODOs); per the baseline-doc analysis the next move is a post-extract pairwise-content dedup pass, tracked for v2.6.

Sample misses, sample false positives, the per-fixture detail, the v1.0 → v1.1 delta analysis, and the methodology are all in the baseline doc. We'd rather publish numbers we can defend on cross-examination than shop a leaderboard score that drifts the moment the upstream model updates.

LongMemEval-50 (cross-corpus sanity check, bench/longmemeval/): on a deterministic 50-question subset of LongMemEval-S-cleaned, our literal-token evidence-preservation rubric scores 0 / 50 full + 2 / 50 partial with gpt-4o-mini (~12 min, ~\$0.40). This is a deliberately strict proxy ("did every key token of the upstream answer survive into our extracted memories?", not LongMemEval native QA correctness — see the spike doc §4.3 for the rubric); 0/50 says ai-memory is not pointed at open-domain QA over a 500-turn haystack, and the per-question matched/total counts in the baseline doc show where partial signal does land (single-session-preference: 3-6 of 17-43 tokens consistently). LongMemEval, LoCoMo, et al. measure runtime recall (did the agent remember a fact); we measure extraction (did we get the right structured artefact out of the chat). Different layer, different question — see also the category-positioning ADR.

Other things it handles

- Token savings — context compresses thousands of turns into a focused prompt (typically 90%+ reduction vs. pasting raw history).
- Team-aware — per-author subdirectories under .ai-memory/{author}/, no merge conflicts when two people commit memories from the same project.
- Cross-device portable — export / import round-trip the whole store as a versioned JSON bundle.
- Zero config, zero API key — npx ai-memory-cli extract works immediately with the built-in free model; set your own key to remove the 2-conversation limit.

---

FAQ

"Doesn't 1M-token context obsolete you?"

Short answer: long context and ai-memory solve different parts of
the same problem. 1M-token windows let the model see a long
conversation in one query; ai-memory makes that conversation's
decisions persistent, reviewable, and shareable across sessions,
machines, and teammates. We answer the question seriously below
because it's the most-cited objection on HN to any structured-memory
tool.

Cost compounds when you re-ship history every query. Frontier
input pricing as of 2026-04 sits at ~\$1–\$3 per 1M tokens
(Anthropic /
OpenAI /
Google AI). A two-week Cursor
session reliably runs 100–300K tokens once tool-call payloads and
file diffs are included; pasting that into every turn costs
\$0.20–\$0.60 per query before you've asked anything. An
AGENTS.md generated from the same conversation is on the order of
1–5K tokens, loaded once per session. Multiply by your team
size and queries-per-day; the gap is two orders of magnitude.

Long-context retrieval still degrades on non-headline
information. "Lost in the middle"
(Liu et al. 2023) and
needle-in-haystack at 1M scale
(BABILong, Kuratov et al. 2024)
both show measurable recall drop on multi-hop retrieval past
~128–256K tokens, even on models that advertise 1M-token windows.
Long context works well for the most-recent and most-prominent
turns; it degrades on the everyday "wait, what did we decide about
X three weeks ago?" question — exactly the queries memory tools are
designed for. Extraction is lossless on the only signal that
matters (the typed decision / convention / architecture).

Long context is per-machine; AGENTS.md is per-repo. Your
laptop's chat history doesn't help your teammate's first day. A
.ai-memory/ directory committed to git does — it's reviewable in
PRs, branchable, revertable, and re-readable by every editor on
every machine that clones the repo. See
What only ai-memory does — points 3
and 4 are the long form.

We'll re-spike this FAQ if (a) sub-\$0.50/M frontier pricing ships,
(b) long-context benchmarks show <5% retrieval degradation past
500K, or (c) editors start shipping native cross-session
conversation compression. Trigger list and full reasoning are in
docs/1m-context-faq-spike-2026-04-27.md.

---

Quick Start

```bash