aimem

A local-first MCP (Model Context Protocol) memory server that gives Claude Code, Cursor, Windsurf, and any other MCP-compatible AI coding assistant persistent, project-scoped memory across chat sessions.

aimem solves AI memory loss in long coding sessions: no more re-explaining your architecture, credentials, or past decisions every time you start a new chat. It's an offline, zero-API-key alternative to cloud-based AI memory services — SQLite + local vector search (sqlite-vec) + a bundled embedding model, stored inside each project's own .aimem/ folder. No external database, no cloud API, no account required. Everything runs on your machine and never leaves it.

Status: v0.2.3 — published on npm as aimem-mcp. Core functionality, reliability hardening, hybrid search, stale-fact invalidation, and the local inspection CLI are all complete and tested (Phases 1–9). Cross-client validation and real-world daily use are in progress. See CHANGELOG.md for release notes and docs/knowledge/setup/current-project-state.md for the exact current state.

Why

Long AI coding sessions eventually hit the same wall: the context window fills up, older details get dropped or summarized away, and you end up re-explaining the same architecture, credentials, and decisions over and over — in the same session, and every time you start a new one. Bigger context windows push the problem back but never solve it; they still cost tokens, still degrade reasoning as they fill, and still forget eventually.

aimem treats this as a memory architecture problem, not a context size problem. Instead of cramming everything into the context window, an aimem-connected agent stores what actually matters — credentials, decisions, architecture facts, bug fixes — in a small local database, and retrieves only what's relevant, when it's relevant.

How it works

┌───────────────────────────────────────────────────────────────────────────┐
│                          Developer's Local Machine                        │
│                                                                             │
│  ┌───────────────────────┐                                                │
│  │   AI Client Process    │                                                │
│  │  (Claude Code, Cursor, │                                                │
│  │   Windsurf, Claude     │                                                │
│  │   Desktop, Gemini CLI, │                                                │
│  │   Codex, ...)          │                                                │
│  └───────────┬────────────┘                                                │
│              │  MCP protocol (JSON-RPC 2.0 over stdio)                     │
│              ▼                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                     aimem MCP Server (Node.js/TS)                    │  │
│  │   Tool Router → Capture Engine → Conflict/Versioning Engine          │  │
│  │              ↘ Retrieval Engine ↗                                    │  │
│  │                    Storage Engine ←→ Embedding/Search Engine         │  │
│  └────────────────────┬────────────────────────────────────────────────┘  │
│                       ▼                                                    │
│         <project_root>/.aimem/memory.db  (SQLite + sqlite-vec, WAL mode)   │
│         local ONNX embedding model, bundled at install — no API key       │
│                                                                             │
│      Nothing above ever leaves the machine. No network calls at runtime.  │
└─────────────────────────────────────────────────────────────────────────┘

Memory is captured three ways, all driven by the AI's own judgment rather than a background process:

• Event-based — the moment the AI notices something worth remembering (a credential, a decision, a bug fix), it's stored immediately.
• Turn-count based — a periodic safety-net scan every ~10–15 exchanges catches anything the event trigger missed.
• Context-threshold based — as the AI senses its own context window filling up, it runs one last thorough save before older messages get dropped.

At the start of every new chat, the AI always checks whether memory exists for the project and asks where to pick up — it never silently stays quiet, and never dumps the entire memory store into context at once.

See docs/architecture/system-overview.md for the full component breakdown and docs/architecture/data-flow.md for sequence diagrams of every operation.

Tools

| Tool | Purpose | |---|---| | memory_get_project_context | Called at the start of every new session — reports whether memory exists and a short summary | | memory_search | Hybrid keyword + semantic search over stored memory, scoped to what's relevant — combines SQLite FTS5 exact-term matching with vector similarity via Reciprocal Rank Fusion, so an exact identifier (an env var name, a literal credential string) surfaces reliably even when a semantically-similar-but-different fact would otherwise outrank it | | memory_store | Event-based capture of a single memory-worthy fact, the moment it's noticed | | memory_scan | Batch capture for periodic and context-threshold safety-net passes | | memory_remember | Manual override — stores unconditionally when the user explicitly says "remember this" | | memory_confirm_update | Resolves a detected conflict between new and existing memory, with full version history | | memory_invalidate | Marks a stored fact as no longer true, with no replacement value — preserved in version history but excluded from search/context |

Full request/response schemas: docs/architecture/api-design.md.

Inspecting memory from the terminal

aimem-inspect is a second, independent binary — a human-facing local CLI for looking at .aimem/memory.db directly, with no AI client involved:

cd your-project
aimem-inspect list                       # every entity and its current observations, as JSON
aimem-inspect search "staging database"  # the same hybrid search memory_search uses
aimem-inspect export                     # full graph as JSON (including invalidated facts) — for backup/migration
aimem-inspect repair --yes               # restore from the rolling backup after corruption

It's installed automatically alongside the MCP server — no separate step. repair refuses to do anything if the live database already passes its own integrity check (even with --yes), and only restores from the backup once the live file is genuinely broken, a valid backup exists, and --yes is passed — see docs/knowledge/setup/usage-guide.md for the exact flow.

Design principles

• Local-first, always. Memory lives in <project_root>/.aimem/memory.db — a single portable SQLite file that moves with the project, survives renames, and is gitignored by default.
• Zero external dependencies. No Docker, no database server, no cloud API, no mandatory API key. The embedding model is bundled into the npm package at install time.
• Project-scoped, not global. Each project's memory is fully isolated. There's no cross-project or organization-wide memory in v1 — that's an explicit, deliberate scope boundary.
• Never silently overwrite. If new information contradicts something already stored, aimem flags the conflict and asks for confirmation before updating — old values are archived, not deleted.
• Fail loud, never crash. A missing memory file is a normal fresh start. A corrupted one is reported with an exact, actionable error — the server never crashes the host AI client's connection.
• Recoverable, not just resilient. A rolling backup is taken before every risky write; if .aimem/memory.db is ever corrupted, aimem-inspect repair can restore it, but only with your explicit confirmation — recovery is never a decision an AI agent makes on your behalf.

The full reasoning behind every major decision — including real, non-obvious bugs found along the way (a missing shebang, a symlink-resolution bug that silently broke every real install path, an FTS5 index-backfill quirk, and a hybrid-search ranking bug caught during a pre-publish hardening pass) — is recorded in docs/decisions/ADR.md.

Installation

npm install -g aimem-mcp

Claude Code — register it once, available in every project from then on:

claude mcp add aimem-mcp npx aimem-mcp -s user

Any other MCP client (Cursor, Windsurf, Claude Desktop, ...) — add to your client's MCP config:

{
  "mcpServers": {
    "aimem-mcp": {
      "command": "npx",
      "args": ["aimem-mcp"]
    }
  }
}

If your Node.js was installed via a version manager (nvm, fnm, volta) — MCP clients often can't find node/npx on PATH this way; use absolute paths instead. See docs/knowledge/setup/install-guide.md for the exact fix.

Full install steps, verification, and troubleshooting: docs/knowledge/setup/install-guide.md. For what actually happens once it's running — how memory gets created and used day to day — see docs/knowledge/setup/usage-guide.md.

Development

npm install            # installs dependencies and bundles the local embedding model
npm run build           # compiles TypeScript to dist/
npm test                # fast unit + integration tests (134 tests)
npm run test:coverage    # same suite, with a v8 coverage report
npm run test:e2e         # spawns the real compiled server over stdio (10 tests)
npm run lint              # ESLint

This project follows a strict phase-based development discipline documented in docs/implementation/phases.md and docs/RULES.md — every change is tracked in docs/AGENT-LOG.md, and every non-trivial decision has a corresponding entry in docs/decisions/ADR.md.

Documentation

All project documentation lives under docs/ on GitHub (not shipped inside the npm package itself, to keep install size down — the links below always point at GitHub):

| Doc | Purpose | |---|---| | docs/RULES.md | Enforceable project rules — tech stack, naming, security, testing, phase discipline | | docs/AGENT-LOG.md | Task log tracking every phase and task | | docs/PROMPT.md | Session-start prompts for agents continuing this project | | docs/requirements/PRD.md | Product requirements — problem, goals, non-goals, success metrics | | docs/requirements/functional-requirements.md | Numbered functional requirements (FR-*) | | docs/architecture/system-overview.md | Full architecture diagram, component responsibilities, tech stack | | docs/architecture/data-flow.md | Sequence diagrams for every major operation | | docs/architecture/api-design.md | MCP tool schemas, request/response formats, error codes | | docs/implementation/phases.md | Phase-by-phase build plan with checkboxes | | docs/implementation/estimation.md | Effort estimates, dependencies, risks, milestones | | docs/knowledge/coding-standards.md | File structure, naming, TypeScript rules, git conventions | | docs/knowledge/error-handling.md | Error format, exact error messages, handling layers | | docs/knowledge/security-standards.md | Security principles, data handling, permissions | | docs/knowledge/testing-guide.md | Testing rules, test types, examples | | docs/knowledge/setup/install-guide.md | Install prerequisites, steps, troubleshooting | | docs/knowledge/setup/usage-guide.md | How memory actually works day to day — first use, every session after, conflicts, searching | | docs/knowledge/setup/agent-instructions.md | Making your AI agent prefer aimem over its own built-in memory — per-agent instruction file snippets | | docs/knowledge/setup/current-project-state.md | What exists right now vs. what's still pending | | docs/modules/ | Per-component design docs (MCP server, storage, embeddings, capture, retrieval, conflict/versioning, aimem-inspect CLI) | | docs/workflows/ | Step-by-step workflow walkthroughs for real usage scenarios | | docs/decisions/ADR.md | Architecture decision records — every major decision with its reasoning and trade-offs |

License

MIT © 2026 Yogesh Joshi