local-memory-mcp

<!-- studiomeyer-mcp-stack-banner:start -->
> **Part of the [StudioMeyer MCP Stack](https://studiomeyer.io)** — Built in Mallorca 🌴 · ⭐ if you use it
<!-- studiomeyer-mcp-stack-banner:end -->

# local-memory-mcp


<!-- badges -->
[![npm version](https://img.shields.io/npm/v/%40studiomeyer%2Flocal-memory-mcp?style=flat-square&color=cb3837&logo=npm&label=npm)](https://www.npmjs.com/package/@studiomeyer/local-memory-mcp)
[![npm downloads](https://img.shields.io/npm/dm/%40studiomeyer%2Flocal-memory-mcp?style=flat-square&color=cb3837&logo=npm&label=installs%2Fmo)](https://www.npmjs.com/package/@studiomeyer/local-memory-mcp)
![License](https://img.shields.io/github/license/studiomeyer-io/local-memory-mcp?style=flat-square&color=22c55e&label=license)
![Last commit](https://img.shields.io/github/last-commit/studiomeyer-io/local-memory-mcp?style=flat-square&color=88c0d0&label=updated)
![GitHub stars](https://img.shields.io/github/stars/studiomeyer-io/local-memory-mcp?style=flat-square&color=ffd700&logo=github&label=stars)
<!-- /badges -->**Persistent local memory for Claude, Cursor & Codex. 25 tools. Hybrid retrieval (BM25 + vector cosine, RRF). Bi-temporal asOf queries + fact supersession. LLM-free contradiction detection + reflection. Portable JSON export/import. Multilingual embeddings. No cloud. No API keys.**

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![npm](https://img.shields.io/npm/v/@studiomeyer/local-memory-mcp)](https://www.npmjs.com/package/@studiomeyer/local-memory-mcp)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](tsconfig.json)

Your AI assistant forgets everything when you close the chat. This fixes that.

Learnings, decisions, people, projects — stored in a **single SQLite file** on your machine that never leaves your computer. Built-in Knowledge Graph, duplicate detection, FTS5 keyword search, and (new in v2) **hybrid retrieval** that fuses BM25 with on-device vector cosine via Reciprocal Rank Fusion. The embedding model is multilingual (DE / EN / ES / 100+ languages) and runs locally — no API keys, no cloud.

📄 **Deep dive:** [WHITEPAPER.md](WHITEPAPER.md) — architecture, design principles, the local-first contract, and an honest comparison vs. other memory systems.

> **Not affiliated with [`danieleugenewilliams/local-memory-releases`](https://github.com/danieleugenewilliams/local-memory-releases)** — that is a different "Local Memory" project with the same descriptive name. This package is published as [`@studiomeyer/local-memory-mcp`](https://www.npmjs.com/package/@studiomeyer/local-memory-mcp) — always use the scoped name to disambiguate.

## A note from us

We have been building tools and systems for ourselves for the past two years. The fact that this repo is small and has few stars is not because it is new. It is because we only just decided to share what we have built. It is not a fresh experiment, it is a long story with a recent commit.

We love building things and sharing them. We do not love social media tactics, growth hacks, or chasing stars and followers. So this repo is small. The code is real, it gets used, issues get answered. Judge for yourself.

If it helps you, sharing, testing, and feedback help us. If it could be better, an issue is more useful. If you build something with it, tell us at hello@studiomeyer.io. That genuinely makes our day.

From a small studio in Palma de Mallorca.

## Quick Start

### Claude Code

```bash
claude mcp add memory -- npx -y @studiomeyer/local-memory-mcp
```

### Claude Desktop

**Easiest: one-click MCPB bundle.** v2.0.0 ships pre-built `.mcpb` bundles for every major desktop platform — download the one for your OS from the [latest release](https://github.com/studiomeyer-io/local-memory-mcp/releases/latest) and double-click. Claude Desktop walks you through the install — no JSON editing, no `npm install`, no terminal.

| Platform | Bundle |
|---|---|
| Linux x64 | `local-memory-mcp-2.2.0-linux-x64.mcpb` |
| macOS Apple Silicon | `local-memory-mcp-2.2.0-darwin-arm64.mcpb` |
| macOS Intel | `local-memory-mcp-2.2.0-darwin-x64.mcpb` |
| Windows x64 | `local-memory-mcp-2.2.0-win32-x64.mcpb` |

Each bundle is platform-specific because `better-sqlite3` is a native module — the matching `.node` binary is shipped inside the bundle so you don't need a build toolchain.

**Manual config** (all platforms — add to `claude_desktop_config.json`, see [Settings > Developer > Edit Config](https://modelcontextprotocol.io/quickstart/user)):

```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@studiomeyer/local-memory-mcp"]
    }
  }
}
```

### Cursor / VS Code

Add to `.cursor/mcp.json` or `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@studiomeyer/local-memory-mcp"]
    }
  }
}
```

### Codex

```toml
# ~/.codex/config.toml
[mcp_servers.memory]
command = "npx"
args = ["-y", "@studiomeyer/local-memory-mcp"]
```

## Automatic session tracking

You can make session tracking fully automatic so you never have to think about it.

**Claude Code (CLAUDE.md):** Add this line to your project's `CLAUDE.md`:

```
Always call memory_session_start at the beginning of each conversation and memory_session_end when done.
```

**Claude Code (Hook):** For a system-wide setup, add a SessionStart hook in `~/.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"Call memory_session_start now.\"}}'",
        "timeout": 5
      }]
    }]
  }
}
```

Both approaches make Claude call `memory_session_start` automatically. The CLAUDE.md way is simpler, the hook way works across all projects.

## What it does

When you start a conversation, the server loads context from your last sessions so the AI knows what you were working on.

During the conversation, the AI stores patterns, insights, and mistakes via `memory_learn`. It records facts about people, projects, and tools via `memory_entity_observe` — building a knowledge graph over time. Every stored row is also embedded into a local 384-dim vector via the multilingual-e5-small model.

When you search, the unified `memory_search` runs **hybrid retrieval**: FTS5 with BM25 ranking is fused with vector cosine via Reciprocal Rank Fusion (RRF, k=60). That bridges vocabulary mismatches ("send" finds "publish"), works across DE / EN / ES / 100+ languages, and matches even when the query has no exact token overlap with the stored content. If the vector extension can't load on your machine, search transparently falls back to FTS5-only — nothing breaks, you just lose the semantic half.

The duplicate gatekeeper still prevents storing the same information twice.

## Hybrid Search (v2.0.0+)

```text
memory_search({ query: "...", mode: "hybrid" })   // default
memory_search({ query: "...", mode: "fts" })       // keyword only
memory_search({ query: "...", mode: "vector" })    // cosine only
```

**Architecture**

- `search_fts` (FTS5, BM25) — keyword recall, the v1 path.
- `embeddings` (`sqlite-vec` `vec0` virtual table, float[384]) — vector recall.
- Reciprocal Rank Fusion (k=60) combines the two when `mode: "hybrid"`.
- Embeddings come from `Xenova/multilingual-e5-small` (Apache-2.0) via Transformers.js, q8-quantized (~30 MB cache). Model loads lazily on the first embed call; runs entirely on CPU.
- Auto-embed-on-insert covers learnings, decisions, and entity observations. Entities themselves are not embedded — their attached observations carry the semantic surface.

**Multilingual.** The default model is trained on 100+ languages with strong DE/EN/ES retrieval. Mixing languages in your stored data is fine — query in one language and the cosine half still surfaces relevant results in another.

**Environment overrides**

- `MEMORY_EMBED_DISABLED=1` — force FTS5-only (e.g. air-gapped or corporate-proxy network).
- `MEMORY_EMBED_MODEL=...` — swap in a different Transformers.js feature-extraction model.
- `MEMORY_EMBED_CACHE_DIR=...` — override the Transformers.js cache location.
- `MEMORY_EMBED_DTYPE=fp32|fp16|q8|q4` — model quantization (default `q8`).

## Lifecycle + Reflection (v2.1.0+)

v2.1 closes the gap between "store a fact" and "manage a memory over time". The schema has carried `archived`, `lifecycle_state`, `valid_from`, and `valid_to` since v1, but no tool exposed them. Now four tools do.

### Bi-temporal asOf — "what did I know on date X?"

```text
memory_entity_open({ id: "...", asOf: "2026-04-15" })
```

Returns the entity plus the observation set whose validity window contained `2026-04-15`. The filter is `valid_from <= asOf AND (valid_to IS NULL OR valid_to > asOf)`. Accepts any format SQLite's `datetime()` recognizes: ISO 8601 (`2026-04-15T00:00:00Z`), SQLite-style (`2026-04-15 00:00:00`), or date-only (`2026-04-15`). Without `asOf` you get the legacy live-view (every observation with `valid_to IS NULL`).

**Design choice — valid-time only, not full bi-temporal.** SQL:2011, XTDB, Datomic offer two-axis bi-temporal (valid-time × transaction-time). We do valid-time only; transaction-time lives passively in `created_at` but isn't queryable as a separate axis. For a local AI-memory product the question is "what did the AI *know* about X on date Y" — that's valid-time. Full bi-temporal matters for regulated audit trails (insurance, banking) — if you need it, reach for XTDB.

**Scale note.** The asOf predicate wraps `valid_from` in SQLite's `datetime()` for format-robust comparisons, which means the planner can't use an index on the column directly. For corpora of <1000 observations per entity (typical) the scan is sub-millisecond. If you have an entity with 10k+ observations, add an expression index — `CREATE INDEX idx_obs_valid_from_dt ON entity_observations(datetime(valid_from))` — and the predicate becomes sargab