aimem
README.md
# aimem
**Your AI coding assistant forgets. Your project shouldn't.**
[](https://www.npmjs.com/package/aimem-mcp)
[](https://www.npmjs.com/package/aimem-mcp)
[](LICENSE)
[](package.json)
A local MCP memory server for Claude Code, Cursor, Windsurf, and any other MCP client. It stores what matters about **this** project — decisions, credentials, architecture, bug fixes — and, in v0.3.0, the **raw conversation history** too. Search it next session instead of re-explaining.
No account. No API key. No Docker. Nothing leaves your machine.
| | |
|---|---|
| **Where it lives** | `<project>/.aimem/memory.db` (gitignored) |
| **How it searches** | Hybrid keyword + semantic (SQLite FTS5 + local MiniLM) |
| **What it needs** | Node.js 20 only |
- **Two kinds of memory, one file** — curated facts (`memory_search`) and full raw conversation history (`memory_search_history`), both searchable, both local.
- **Hybrid search, not just vectors** — semantic similarity fused with exact-term FTS5 matching, so file paths, error strings, and identifiers actually surface.
- **Runs fully offline** — the embedding model is bundled at install; no API key, no account, no network call at query time.
- **Works with any MCP client** — Claude Code, Cursor, Windsurf, Claude Desktop, Codex, Gemini CLI.
- **Conflict-aware, not silently overwritten** — a new fact that contradicts an old one asks first; nothing gets lost, just archived.
- **Inspectable without an agent** — `aimem-inspect` is a plain CLI: list, search, export, repair, no MCP client required.
---
## Install
**1. Install the package** (Node.js 20.x):
```bash
npm install -g aimem-mcp
```
**2. Connect your editor** — pick one:
Claude Code (once, every project after that):
```bash
claude mcp add aimem-mcp npx aimem-mcp -s user
```
Cursor, Windsurf, Claude Desktop, Codex, Gemini CLI — add to your MCP config:
```json
{
"mcpServers": {
"aimem-mcp": {
"command": "npx",
"args": ["aimem-mcp"]
}
}
}
```
If Node was installed with nvm / fnm / volta and the tools never appear, use absolute paths — that's the most common install miss. Full steps: [install guide](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/knowledge/setup/install-guide.md).
Then tell the agent to prefer aimem over its own notes: [agent instructions](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/knowledge/setup/agent-instructions.md).
---
## New in 0.3.0 — two kinds of memory, one file
| | **Facts** (`memory_search`) | **History** (`memory_search_history`) |
|---|---|---|
| What | Distilled things worth keeping: “we use Postgres”, “staging host is db1” | The actual chat: what you asked, what the agent said, which tools ran |
| Who writes it | The agent, when something is worth remembering | Automatic — tails this project's Claude Code transcripts |
| Best for | Architecture, credentials, decisions, bug fixes | “What did we try last Thursday?” / the exact command that worked |
| Clients | Any MCP client | History ingest is Claude Code today; fact memory still works everywhere |
History search is hybrid too (vector + keyword), with filters for time, role, kind (`message` / `tool_call` / `event`), and session. Each hit has an `id` — `memory_get_history_item` returns the full text when the 300-character summary isn't enough.
```
You: "What did we decide about the auth service?"
Agent: memory_search → "JWT, 15-minute expiry, Redis for sessions."
You: "What exact error did we hit when we first wired sqlite-vec?"
Agent: memory_search_history → the original tool result, not a paraphrase.
```
---
## Why this exists
A bigger context window only postpones forgetting. Old turns get summarized away, tokens get expensive, and Monday's chat doesn't remember Friday's decision.
aimem treats that as a **memory** problem: keep a small local database per project, retrieve only what's relevant, never dump the whole store into the prompt.
At the start of a new chat the agent checks `memory_get_project_context` (including whether that summary has gone stale) and asks where to pick up. It does not stay silent, and it does not paste everything.
Day-to-day flow: [usage guide](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/knowledge/setup/usage-guide.md).
---
## How it works
```mermaid
flowchart LR
A[Claude Code / Cursor / Windsurf] -->|MCP stdio| B[aimem]
B --> C[Facts: store / search / conflicts]
B --> D[History: ingest + search]
C --> E[".aimem/memory.db"]
D --> E
E --> F[sqlite-vec + FTS5 + local ONNX model]
```
Everything in that diagram stays on your disk. The embedding model is bundled at install. There is no telemetry and no cloud call at runtime.
Architecture and sequence diagrams: [system overview](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/architecture/system-overview.md) · [data flow](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/architecture/data-flow.md).
---
## Tools
**Facts**
| Tool | When |
|---|---|
| `memory_get_project_context` | First call of every new session |
| `memory_search` | Need a durable fact, not the whole store |
| `memory_store` | Something worth remembering, right now |
| `memory_scan` | Safety-net every ~10–15 turns, or before context drops |
| `memory_remember` | You said “remember this” |
| `memory_confirm_update` | New fact contradicts an old one — confirm or keep the old |
| `memory_invalidate` | That fact is no longer true; keep it in history, hide it from search |
**History (v0.3.0)**
| Tool | When |
|---|---|
| `memory_search_history` | Recall what was actually said or done, including past sessions |
| `memory_get_history_item` | The 300-character summary isn't enough — fetch the full record |
Schemas: [API design](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/architecture/api-design.md).
---
## Inspect it yourself
`aimem-inspect` is a separate CLI (installed with the package). No MCP client required:
```bash
cd your-project
aimem-inspect list # entities + current observations
aimem-inspect search "staging database" # same hybrid search as memory_search
aimem-inspect export # full JSON, including invalidated facts
aimem-inspect repair --yes # restore from backup only if the live DB is corrupt
```
`repair` will not overwrite a healthy database, even with `--yes`. History browsing from this CLI is not in 0.3.0 yet — use the two history tools from the agent for now.
---
## Design rules that don't move
- **Local-first.** One SQLite file per project. Moves with the folder. Gitignored by default.
- **No silent overwrite.** Conflicts ask; old values are archived, not deleted.
- **Fail loud, never crash the host.** Missing DB = fresh start. Corrupt DB = a clear error, not a dead MCP connection.
- **Recoverable.** Rolling backup before risky writes; you confirm any restore.
- **History is verbatim.** Transcript ingest stores real messages and tool I/O, which can include secrets you pasted. Treat `.aimem/` the same way you treat a `.env`.
Why those choices: [ADR.md](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/decisions/ADR.md).
---
## Documentation
User-facing first:
| Doc | Purpose |
|---|---|
| [Install](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/knowledge/setup/install-guide.md) | Prerequisites, client setup, nvm PATH fix |
| [Usage](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/knowledge/setup/usage-guide.md) | First session, pickup, conflicts, search |
| [Agent instructions](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/knowledge/setup/agent-instructions.md) | Make the model actually call aimem |
| [Changelog](CHANGELOG.md) | What landed in each release |
The rest of the tree — PRD, phases, modules (including [history-engine](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/modules/history-engine.md)), workflows, current project state — is under [`docs/`](https://github.com/yogesh-joshi-0333/aimem/tree/master/docs). Docs are on GitHub only (not inside the npm tarball) so install stays smaller.
---
## Development
```bash
npm install # dependencies + bundled embedding model
npm run build # TypeScript → dist/
npm test # fast suite (298 tests)
npm run test:coverage
npm run test:e2e # real subprocess MCP (30 tests)
npm run lint
```
Phase discipline: [phases](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/implementation/phases.md) · [RULES](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/RULES.md) · [AGENT-LOG](https://github.com/yogesh-joshi-0333/aimem/blob/master/docs/AGENT-LOG.md).
---
## License
[MIT](LICENSE) © 2026 Yogesh Joshi
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues