# aimem

**Your AI coding assistant forgets. Your project shouldn't.**

[![npm version](https://img.shields.io/npm/v/aimem-mcp.svg)](https://www.npmjs.com/package/aimem-mcp)
[![npm downloads](https://img.shields.io/npm/dm/aimem-mcp.svg)](https://www.npmjs.com/package/aimem-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js Version](https://img.shields.io/node/v/aimem-mcp.svg)](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