ai-memory
README.md
# ai-memory
[](https://www.npmjs.com/package/ai-memory-cli)
[](https://github.com/hyxnj666-creator/ai-memory/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
> Turn AI editor chat history into typed Markdown + `AGENTS.md` rules — local-first, git-trackable, zero `.remember()` calls.
```bash
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.
> **[中文文档](README.zh-CN.md)**
---
## 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](docs/benchmarks/cceb-baseline.md), `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](docs/benchmarks/cceb-baseline.md). 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/`](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](docs/cceb-v1.1-and-longmemeval-spike-2026-04-27.md) 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](docs/benchmarks/cceb-baseline.md#longmemeval-50--gpt-4o-mini--2026-04-27-v25-08-evidence-preservation-rubric) 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](docs/decisions/2026-04-25-category-positioning.md).
### 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](https://www.anthropic.com/pricing) /
[OpenAI](https://openai.com/api/pricing) /
[Google AI](https://ai.google.dev/pricing)). 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](https://arxiv.org/abs/2307.03172)) and
needle-in-haystack at 1M scale
([BABILong, Kuratov et al. 2024](https://arxiv.org/abs/2406.10149))
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](#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`](docs/1m-context-faq-spike-2026-04-27.md).
---
## Quick Start
```bash
# Initialise project (optionally register ai-memory as an MCP server)
npx ai-memory-cli init --with-mcp
# Extract — works out of the box with the built-in free model (no API key needed)
# Limited to 2 conversations per run on the built-in key.
npx ai-memory-cli extract
# Unlock unlimited extractions — set your own key (any OpenAI-compatible provider)
export AI_REVIEW_API_KEY=sk-... # or OPENAI_API_KEY
# One-shot health check — verifies editors, API key, store, MCP config
npx ai-memory-cli doctor
# Search your knowledge base
npx ai-memory-cli search "authentication"
# Generate Cursor Rules from conventions
npx ai-memory-cli rules
# Generate a context prompt and copy to clipboard
npx ai-memory-cli context --copy
# Commit to git
git add .ai-memory/ && git commit -m "chore: add ai-memory knowledge base"
```
---
## Commands
### `try` — No-API-key demo (30 seconds, zero credentials)
Bootstraps a hand-curated 3-memory store in a tmp dir, runs the real `rules --target agents-md` pipeline against it, and prints the generated AGENTS.md inline. No LLM call, no API key, no changes to your working directory — just a concrete answer to "what does this thing actually produce?" before you commit to setup.
```bash
npx ai-memory-cli try # full demo, tmp dir cleaned up afterwards
npx ai-memory-cli try --keep # leave the tmp scenario on disk for inspection
npx ai-memory-cli try --json # structured output (counts, AGENTS.md content, paths)
```
The bundled scenario contains 1 decision (PKCE auth flow), 1 architecture record (event-sourced billing audit log), and 1 convention (Relay-style cursor pagination) across two authors. Only conventions and decisions land in AGENTS.md — the same filter the real `rules` command uses on your own memories.
### `doctor` — One-shot health check
Run this after `try` if you decide to set ai-memory up against your real chat history. It diagnoses the six most common setup problems and tells you exactly how to fix each one.
```bash
npx ai-memory-cli doctor # human-readable report
npx ai-memory-cli doctor --no-llm-check # skip live API call (offline / CI)
npx ai-memory-cli doctor --json # structured output for automation / bug reports
```
Checks cover: Node.js version, detected editors (Cursor / Claude Code / Windsurf / Copilot / Codex CLI + conversation counts), LLM provider + live connectivity probe, memory store + author resolution, embeddings freshness, and MCP config registration. Exit code is `0` if everything passes, `1` if any check fails. When no API key is configured, `doctor` now points at `try` as the no-key fast path.
### `list` — Show available conversations
```bash
npx ai-memory-cli list # show all conversations
npx ai-memory-cli list --source cursor # only Cursor conversations
npx ai-memory-cli list --json # JSON output
```
### `extract` — Extract memories from conversations
```bash
npx ai-memory-cli extract # extract all conversations
npx ai-memory-cli extract --incremental # only new conversations
npx ai-memory-cli extract --pick 3 # only conversation #3
npx ai-memory-cli extract --pick 1,4,7 # multiple conversations
npx ai-memory-cli extract --id b5677be8 # match by ID prefix
npx ai-memory-cli extract --since "3 days ago" # only recent conversations
npx ai-memory-cli extract --type decision,todo # only specific types
npx ai-memory-cli extract --dry-run # preview without writing
npx ai-memory-cli extract --force # overwrite existing files
npx ai-memory-cli extract --author "alice" # override author name
npx ai-memory-cli extract --redact # scrub secrets / PII before LLM call (v2.5+)
npx ai-memory-cli extract --verbose # show LLM request details
npx ai-memory-cli extract --json # JSON output (CI friendly)
```
> **No API key?** `extract` automatically falls back to a built-in free model (DeepSeek-V4-Flash via SiliconFlow), limited to **2 conversations per run** and **20 chunks per conversation** (uniform sampling — covers full conversation breadth, not just the opening turns). Set `AI_REVIEW_API_KEY` or `OPENAI_API_KEY` to remove both limits.
#### `--redact` — scrub secrets / PII / internal hostnames before sending to the LLM (v2.5+)
`extract`, `summary`, and `context --summarize` ship conversation excerpts to your configured LLM provider. "Local-first" applies to the **storage layer** — `.ai-memory/` is plain Markdown that we never upload — but the **extraction call** is necessarily an outbound HTTPS request. If your chat history contains accidentally pasted API keys, internal hostnames in stack traces, or customer email addresses in logs, `--redact` scrubs them before the request leaves your machine.
```bash
$ ai-memory extract --redact
...
Redaction: 5 items scrubbed before LLM (118 chars) — 3 openai-key, 2 email
```
Default-on rules (10): OpenAI / Anthropic / AWS / GitHub / Slack / GCP / Stripe API keys, RFC5322 emails, and `*.internal` / `*.corp` / `*.local` / `*.lan` / `*.intra` hostnames. Two opt-in rules (`jwt`, `aws-secret-key`) are off by default because they have high false-positive rates against long base64 strings; enable them via `.ai-memory/.config.json`:
```json
{
"redact": {
"enabled": true,
"enableOptional": ["jwt"],
"rules": [{ "name": "internal-jira", "pattern": "JIRA-[0-9]{4,}" }]
}
}
```
CLI overrides config: `--no-redact` always disables, `--redact` always enables. The audit trail (per-rule hit counts) is always on when redaction is on, in both human and `--json` output. The matched value is **never** logged — that would defeat the purpose.
> **Threat model.** Defense-in-depth, **not** a substitute for proper secrets management. The full policy doc — including out-of-scope items (image attachments, retroactive scrubbing of pre-existing memories, structured-PII vault inspection) and the threat-model boundaries — lives at [`docs/redaction-policy-2026-04-26.md`](docs/redaction-policy-2026-04-26.md).
### `search` — Search through extracted memories
```bash
npx ai-memory-cli search "OAuth" # keyword search across all memories
npx ai-memory-cli search "payment" --type decision # filter by type
npx ai-memory-cli search "auth" --author alice # filter by author
npx ai-memory-cli search "API" --include-resolved # include resolved memories
npx ai-memory-cli search "config" --json # JSON output
```
Results are ranked by relevance (title matches > content > context) with highlighted keywords.
### `recall` — Time-travel a memory through git history
Every other "memory" tool flattens its store down to "the latest" — every
superseded version is silently overwritten. Because `.ai-memory/` is plain
Markdown in a git repo, the *full lineage* of every fact is already on disk;
`recall` exposes it as a first-class command.
```bash
npx ai-memory-cli recall "OAuth" # show how the OAuth decision evolved
npx ai-memory-cli recall "OAuth" --include-resolved # include superseded / resolved memories
npx ai-memory-cli recall "API" --type decision # filter by type
npx ai-memory-cli recall "auth" --all-authors # search across the whole team
npx ai-memory-cli recall "OAuth" --json # structured output (one entry per memory + its commit list)
```
Output looks like:
```
Recall: "OAuth" — 1 memory, 4 commits of lineage
[+] CURRENT Use OAuth 2.0 PKCE for SPA @conor (2026-04-20)
.ai-memory/conor/decisions/2026-04-20-use-oauth-pkce.md
History (4 commits):
a1b2c3d 2026-04-20 conor ~ Tighten OAuth PKCE: require HTTPS-only token endpoint
e4f5g6h 2026-04-15 conor ~ Switch from implicit flow to PKCE
i7j8k9l 2026-03-20 conor + Add OAuth library notes
> git log --follow .ai-memory/conor/decisions/2026-04-20-use-oauth-pkce.md for full diffs
```
- Uses `git log --follow` so renames inside `.ai-memory/` are tracked
transparently.
- Each line shows short SHA, ISO date, author, status code (`+` added, `~`
modified, `-` deleted, `R` renamed), and commit subject.
- **Soft fallback** — outside a git repo, or before the first commit of
`.ai-memory/`, recall still returns the matching memories with a hint
explaining what's missing. There is no scenario where `recall` is worse
than `search`.
- No new runtime dep — pure `node:child_process.execFile` against your
existing `git` with bounded 10s timeouts.
### `rules` — Export conventions as Cursor Rules, AGENTS.md, **and** Anthropic Skills
Generate editor rules that every AI tool reads natively:
```bash
npx ai-memory-cli rules # default: .cursor/rules/ai-memory-conventions.mdc
npx ai-memory-cli rules --target agents-md # AGENTS.md (Codex / Cursor / Windsurf / Copilot / Amp)
npx ai-memory-cli rules --target skills # Anthropic Skills (Claude Code) — v2.5+
npx ai-memory-cli rules --target both # write Cursor Rules + AGENTS.md at default paths
npx ai-memory-cli rules --output my-rules.mdc # custom output (single-target only)
npx ai-memory-cli rules --all-authors # include team conventions
```
`--target agents-md` performs an **idempotent merge**: only the section between
`<!-- ai-memory:managed-section start --> ... end -->` is touched, so any
hand-written content in your `AGENTS.md` is preserved byte-for-byte. Re-running
with no new memories is a no-op (`already-up-to-date`); malformed markers from
a partial edit are reported as a conflict and the file is left untouched.
`--target skills` writes [Anthropic Skills](https://docs.anthropic.com/en/docs/claude-code/skills) under `.claude/skills/`. Three skills get generated, one per long-lived memory type:
| Skill | Source | What it tells Claude |
|---|---|---|
| `.claude/skills/ai-memory-coding-conventions/SKILL.md` | `convention` memories | When writing new code / naming things / designing APIs |
| `.claude/skills/ai-memory-decision-log/SKILL.md` | `decision` memories (status ≠ resolved) | When proposing architectural changes / asked why a choice was made |
| `.claude/skills/ai-memory-system-architecture/SKILL.md` | `architecture` memories | When implementing cross-component features / debugging integration |
Skills are loaded **dynamically** by Claude Code based on the YAML frontmatter `description` matching your request — unlike AGENTS.md (always-on context), the body only enters context when relevant. The schema we target (frozen 2026-04-26) lives at [`docs/skills-schema-snapshot-2026-04-26.md`](docs/skills-schema-snapshot-2026-04-26.md). The `ai-memory-` prefix on skill names is an ownership signal: anything inside `.claude/skills/ai-memory-*/` is **fully regenerated** every run; user-authored skills under any other directory name are left alone.
This is the **conversation-to-rules pipeline** — extract conventions from chat
history, auto-generate the rules files every AI editor reads. No other tool
emits all three of Cursor Rules + AGENTS.md + Anthropic Skills from a single chat-history input.
### `resolve` — Mark memories as resolved
Decisions get overturned. TODOs get completed. Keep your knowledge base fresh:
```bash
npx ai-memory-cli resolve "OAuth" # mark matching memories as resolved
npx ai-memory-cli resolve "OAuth" --undo # reactivate resolved memories
```
Resolved memories are automatically excluded from `context`, `summary`, and `search` results. Use `--include-resolved` to force inclusion.
### `summary` — Generate a project-level summary
```bash
npx ai-memory-cli summary # write/update SUMMARY.md
npx ai-memory-cli summary --output MEMORY.md # custom output path
npx ai-memory-cli summary --focus "payment module" # focus on a topic
npx ai-memory-cli summary --all-authors # include all team members
npx ai-memory-cli summary --include-resolved # include resolved memories
# Scope summary to a single conversation (no LLM cost for the wrong chats)
npx ai-memory-cli summary --list-sources # list conversations first
npx ai-memory-cli summary --source-id b5677be8 # summarize ONE chat
npx ai-memory-cli summary --convo "payment refactor"
```
### `context` — Generate a continuation prompt
For seamlessly resuming work in a new conversation or on another machine:
```bash
npx ai-memory-cli context # generate context block (instant, no LLM)
npx ai-memory-cli context --copy # generate and copy to clipboard
npx ai-memory-cli context --topic "coupon system" # focus on a specific topic
npx ai-memory-cli context --recent 7 # only last 7 days of memories
npx ai-memory-cli context --output CONTEXT.md # write to file
npx ai-memory-cli context --summarize # use LLM for condensed prose summary
npx ai-memory-cli context --all-authors # include all team members
npx ai-memory-cli context --include-resolved # include resolved memories
```
**Scope context to a single conversation** — because in real life you usually want to resume *one* chat, not dump everything:
```bash
# 1. See which conversations produced memories
npx ai-memory-cli context --list-sources
# # Date Source ID Count Types Title
# ------------------------------------------------------------------------------
# 1 2026-04-01 cursor b5677be8 12 D:4 A:3 C:5 resume tool
# 2 2026-03-28 claude-code ff12abc3 7 A:4 T:3 ai-lab
# 2. Copy context from ONE conversation (ID prefix, like git short hash)
npx ai-memory-cli context --source-id b5677be8 --copy
# 3. Or match by conversation title — picks the most recent if multiple match
npx ai-memory-cli context --convo "resume tool" --copy
npx ai-memory-cli context --convo "resume" --all-matching --copy # include every "resume*" chat
```
### `link` — Link memories to the commits that implement them (v2.6)
```bash
npx ai-memory-cli link # scan last 30 days of commits
npx ai-memory-cli link --since "7 days ago" # custom time window
npx ai-memory-cli link --dry-run # preview links without writing
npx ai-memory-cli link --clear-auto # remove all auto-generated links
```
Scans your git log and scores each (memory, commit) pair using weighted token overlap: memory title × 3, type × 2, content × 1 vs commit subject × 3, changed paths × 2, body × 1. High-confidence matches (`score ≥ 0.70`) are written into the memory file as an invisible HTML comment block that the dashboard can surface. The default threshold is conservative — a bad auto-link is worse than no link. Use `--dry-run` first on a real repo to calibrate.
### `init` — Initialize configuration
```bash
npx ai-memory-cli init # detect editors, create config
npx ai-memory-cli init --with-mcp # also register ai-memory as MCP server
npx ai-memory-cli init --schedule # register a daily extract --incremental cron job
npx ai-memory-cli init --unschedule # remove the scheduled task
```
With `--with-mcp`, ai-memory writes / merges `.cursor/mcp.json` and `.windsurf/mcp.json` so your editor picks up the MCP server automatically. With `--schedule`, a daily extraction job is registered with the OS-native scheduler (launchd on macOS, crontab on Linux, Task Scheduler on Windows) — so your knowledge base stays fresh without any manual runs. Both flags are idempotent and safe.
### `export` / `import` — Move memories between machines (NEW)
Cursor / Claude Code conversations live in each machine's local state, so a new laptop starts with no history. `export` and `import` create a portable JSON bundle that round-trips cleanly — same files, same conversation grouping, same `context --source-id` behavior on the destination.
```bash
# On the old machine — export everything (or scope with --source-id / --convo / --type)
npx ai-memory-cli export --output backup.ai-memory.json
npx ai-memory-cli export --source-id b5677be8 --output resume-tool.json # one chat only
npx ai-memory-cli export --convo "coupon" --output coupons.json # match by title
# Copy / commit / share the bundle (it's a plain JSON file)
# On the new machine — preview first, then apply
npx ai-memory-cli import backup.ai-memory.json --dry-run
npx ai-memory-cli import backup.ai-memory.json # default: skip duplicates
npx ai-memory-cli import teammate-bundle.json --author me # remap teammate's memories
npx ai-memory-cli import stale.json --overwrite # replace local copies
# Rebuild embeddings so semantic search/MCP work on the imported memories
npx ai-memory-cli reindex
```
Bundle format is versioned (`version: 1`) and import is **idempotent** — running the same import twice is a no-op (dedup on author + type + date + title).
---
## MCP Server (NEW)
ai-memory can run as an **MCP server**, giving AI editors (Cursor, Claude Code) direct access to your knowledge base — no manual commands needed.
### Setup
Add to your Cursor MCP config (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"ai-memory": {
"command": "npx",
"args": ["ai-memory-cli", "serve"]
}
}
}
```
Or for Claude Code (`.claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"ai-memory": {
"command": "npx",
"args": ["ai-memory-cli", "serve"]
}
}
}
```
### What the AI gets
| MCP Capability | What it does |
|---|---|
| `remember` tool | AI stores decisions/conventions/todos during conversations (auto-indexed) |
| `recall` tool | AI retrieves relevant memories using semantic + keyword hybrid search |
| `search_memories` tool | Full search with type/author/resolved filtering, semantic-aware |
| `project-context` resource | Auto-provides project context when starting a conversation |
Once configured, the AI can automatically remember important decisions and recall them in future sessions — without you running any commands.
### Semantic Search
ai-memory uses **hybrid search** combining semantic similarity (via embeddings), keyword matching, and time decay. This means you can search by meaning, not just exact keywords.
```bash
# Build search index (uses your existing LLM API for embeddings)
npx ai-memory-cli reindex
# Now search works semantically — "database choice" finds "PostgreSQL decision"
npx ai-memory-cli search "database choice"
```
The MCP `recall` and `search_memories` tools use hybrid search automatically. Embeddings are stored locally in `.ai-memory/.embeddings.json` and auto-indexed when using the `remember` tool.
### Manual start (for testing)
```bash
npx ai-memory-cli serve # start MCP server
npx ai-memory-cli serve --debug # with debug logging
```
---
## Watch Mode (NEW)
Automatically extract knowledge when conversations change — zero manual effort:
```bash
npx ai-memory-cli watch
```
Watch mode monitors all detected sources for new conversation activity and runs extraction automatically. It uses file system events (for Cursor/Claude Code) and periodic polling (for all sources) to detect changes.
```
ai-memory watch — auto-extract on conversation changes
Author: conor
Output: .ai-memory/
[+] Watching: Cursor
[+] Watching: Claude Code
Initial scan complete — watching for changes...
10:15:32 [Cursor] "OAuth refactor discussion" (+8 turns) — extracting...
10:15:37 [+] 2 decision, 1 convention
```
Press `Ctrl+C` to stop.
---
## Dashboard (NEW)
Browse, search, and visualize your knowledge base in a local web UI:
```bash
npx ai-memory-cli dashboard
```
Opens `http://localhost:3141` with:
- **Overview** — stats cards, monthly timeline chart, author breakdown, recent activity
- **Memory browser** — real-time search, filter by type/author/status, detail modal
- **Conversations** — one card per chat window that produced memories, with a one-click `context --source-id` copy so you can jump from "which chat did I make that decision in?" to "resume that chat in a new session"
- **Knowledge graph** — interactive D3.js force-directed graph (nodes colored by type, edges by shared conversation or keywords)
- **Quality** — specificity histogram, vague content list, duplicate/subsumed pairs (powered by the v2.2 algorithm stack)
- **Export** — download as JSON, Obsidian vault (with YAML frontmatter), or copy to clipboard
```bash
npx ai-memory-cli dashboard --port 8080 # custom port
```
### Clean up existing memories with the new algorithms
If you upgraded from an older version and want to retroactively apply the v2.2 quality algorithms to remove vague/duplicate memories you accumulated earlier:
```bash
npx ai-memory-cli reindex --dedup --dry-run # preview what would be deleted
npx ai-memory-cli reindex --dedup # actually delete + update index
```
Typical cleanup on a 200+ memory store removes 20–30% as vague/duplicate/subsumed.
---
## Local LLM Support (NEW)
Use Ollama or LM Studio instead of cloud APIs — **no API key needed**:
### Ollama
```bash
# Install Ollama: https://ollama.ai
ollama pull llama3.2 # download a model
ollama pull nomic-embed-text # (optional) for semantic search
export OLLAMA_HOST=http://localhost:11434
export OLLAMA_MODEL=llama3.2 # extraction model
npx ai-memory-cli extract
```
### LM Studio
```bash
# Start LM Studio and load a model
export LM_STUDIO_BASE_URL=http://localhost:1234/v1
export LM_STUDIO_MODEL=your-model-name
npx ai-memory-cli extract
```
Cloud API keys always take priority over local LLM. If you have `OPENAI_API_KEY` or `AI_REVIEW_API_KEY` set, those will be used.
| Variable | Description |
|----------|-------------|
| `OLLAMA_HOST` | Ollama server URL (default: `http://localhost:11434`) |
| `OLLAMA_MODEL` | Model for extraction (default: `llama3.2`) |
| `OLLAMA_EMBEDDING_MODEL` | Model for semantic search (default: `nomic-embed-text`) |
| `LM_STUDIO_BASE_URL` | LM Studio server URL (default: `http://localhost:1234/v1`) |
| `LM_STUDIO_MODEL` | Model name |
---
## Supported Sources
| Source | Data location | Status |
|--------|---------------|--------|
| **Cursor** | `~/.cursor/projects/{name}/agent-transcripts/` | Stable |
| **Claude Code** | `~/.claude/projects/{path}/*.jsonl` | Stable |
| **Windsurf** | `~/AppData/Windsurf/User/workspaceStorage/*/state.vscdb` | Beta |
| **VS Code Copilot** | `~/AppData/Code/User/workspaceStorage/*/chatSessions/*.json` | Beta |
| **Codex CLI** | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | Beta — v2.5+ |
---
## Typical Workflow
### First extraction
```bash
npx ai-memory-cli list # see what conversations are available
npx ai-memory-cli extract # extract everything (few minutes on first run)
npx ai-memory-cli rules # generate Cursor Rules
git add .ai-memory/ .cursor/rules/
git commit -m "chore: add ai-memory knowledge base"
```
### Daily use (incremental)
```bash
npx ai-memory-cli extract --incremental # after a productive coding session
npx ai-memory-cli rules # refresh Cursor Rules
git add .ai-memory/ && git commit -m "chore: update memories"
```
### Starting a new conversation
```bash
npx ai-memory-cli context --copy # copy context to clipboard
# Paste into new Cursor/Claude Code session
```
The output looks like:
```markdown
## Project Context
### Key Decisions (follow without re-discussion)
- **Use OAuth Bridge pattern**: WebView cannot receive redirect directly...
### Conventions (always follow)
- **Never call getServerSideProps in this project**: ...
### Active TODOs
- [ ] Add retry logic to payment webhook handler
```
### Finding specific knowledge
```bash
npx ai-memory-cli search "payment" # find all payment-related memories
npx ai-memory-cli search "auth" --type decision # only decisions about auth
```
---
## Team Workflow
When multiple people use ai-memory in the same git repo, each person's memories are automatically stored in their own subdirectory.
### How it works
Author identity is auto-detected (priority: `--author` CLI flag > `config.author` > `git config user.name` > OS username). No manual setup needed.
```
.ai-memory/
├── conor/
│ ├── decisions/
│ │ └── 2026-04-15-oauth-bridge.md
│ └── todos/
│ └── 2026-04-15-add-retry.md
├── alice/
│ ├── decisions/
│ │ └── 2026-04-16-payment-design.md
│ └── architecture/
│ └── 2026-04-16-module-split.md
└── .config.json
```
### Usage
```bash
# Everyone extracts normally — writes to their own directory
npx ai-memory-cli extract --incremental
# Generate your own context (default: only your memories)
npx ai-memory-cli context --copy
# Include the whole team's memories
npx ai-memory-cli summary --all-authors
npx ai-memory-cli context --all-authors --copy
# Override author name
npx ai-memory-cli extract --author "alice"
```
### Upgrading existing projects
Memories created before v1.3 are stored in flat directories (`.ai-memory/decisions/`). After upgrading:
- Old files are still read normally (backwards compatible), with `author` empty
- New extractions go to `.ai-memory/{author}/decisions/` etc.
- No manual migration required
---
## Cross-Device Workflow
```
Work machine Home machine
──────────── ────────────
Cursor / Claude Code dev work
-> npx ai-memory-cli extract --incremental
-> git add .ai-memory/
git commit && git push
git pull
-> npx ai-memory-cli context --topic "today's work"
-> Paste context into new conversation
-> Seamlessly resume
```
---
## Configuration
`ai-memory` works with zero config. To customize, run `npx ai-memory-cli init` or create `.ai-memory/.config.json` manually:
```jsonc
{
"sources": {
"cursor": { "enabled": true, "projectName": "my-project" },
"claudeCode": { "enabled": true },
"windsurf": { "enabled": true },
"copilot": { "enabled": true }
},
"extract": {
"types": ["decision", "architecture", "convention", "todo", "issue"],
"ignoreConversations": [], // conversation UUIDs to skip
"minConversationLength": 5 // skip very short conversations
},
"output": {
"dir": ".ai-memory",
"summaryFile": "SUMMARY.md",
"language": "zh" // "zh" or "en" — output language for summaries
},
"model": "", // leave empty for auto-selection
"author": "" // leave empty to auto-detect from git config user.name
}
```
### Environment variables
| Variable | Description |
|----------|-------------|
| `AI_REVIEW_API_KEY` | API key (preferred, shared with ai-review-pipeline) |
| `OPENAI_API_KEY` | OpenAI API key |
| `OPENAI_BASE_URL` | Custom OpenAI-compatible API base URL |
| `OPENAI_MODEL` | Model override for OpenAI |
| `ANTHROPIC_API_KEY` | Anthropic API key (requires compatible proxy) |
| `ANTHROPIC_BASE_URL` | Anthropic proxy base URL |
| `AI_REVIEW_BASE_URL` | Custom API base URL |
| `AI_REVIEW_MODEL` | Model to use (default: `gpt-4o-mini`) |
| `OLLAMA_HOST` | Ollama server URL (default: `http://localhost:11434`) |
| `OLLAMA_MODEL` | Ollama model for extraction |
| `OLLAMA_EMBEDDING_MODEL` | Ollama model for semantic search embeddings |
| `LM_STUDIO_BASE_URL` | LM Studio API URL |
| `LM_STUDIO_MODEL` | LM Studio model name |
---
## Output Structure
Each memory is its own file, organized by author and type:
```
.ai-memory/
├── SUMMARY.md # Project summary (from `summary` command)
├── conor/ # Per-author subdirectory
│ ├── decisions/
│ │ ├── 2026-04-12-oauth-bridge-pattern.md
│ │ └── 2026-04-13-async-job-queue-design.md
│ ├── architecture/
│ │ └── 2026-04-10-payment-module-design.md
│ ├── conventions/
│ │ └── 2026-04-08-coding-conventions.md
│ ├── todos/
│ │ └── 2026-04-12-add-retry-logic.md
│ └── issues/
│ └── 2026-04-11-sqlite-locking-fix.md
├── .index/ # Extraction index (auto-managed)
├── .config.json # Configuration (commit this)
└── .state.json # Extraction state (add to .gitignore)
```
Add `.ai-memory/.state.json` to `.gitignore` — it tracks which conversations have been processed and is machine-specific.
---
## CI Integration
```yaml
# .github/workflows/memory.yml
- name: Extract AI memories
run: npx ai-memory-cli extract --incremental --json
env:
AI_REVIEW_API_KEY: ${{ secrets.AI_REVIEW_API_KEY }}
```
---
## Requirements
- Node.js >= 18
- **No API key required to get started** — a free built-in model (DeepSeek-V4-Flash via SiliconFlow) is used automatically when no key is configured, limited to 2 conversations per run.
- For unlimited extractions: set `AI_REVIEW_API_KEY` (or `OPENAI_API_KEY`) to any OpenAI-compatible provider, or use a local LLM (Ollama / LM Studio).
> **Tip:** Node.js 22+ enables richer conversation titles by reading Cursor/Windsurf's database. On Node 18-20, titles are extracted from the first message (still works fine).
## Community
- [Linux DO Discussion](https://linux.do) — Chinese developer community thread
## License
MIT — [Conor Liu](https://github.com/hyxnj666-creator)
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues