AI Memory MCP
README.md
<div align="center">
# AI Memory MCP
### Long-term memory for Claude, ChatGPT and any MCP client — 100% local.
**Your AI forgets every conversation. This fixes it.**
Semantic search across your entire Claude Desktop, ChatGPT and Claude Code history,
exposed to your assistant as an [MCP](https://modelcontextprotocol.io) server.
No cloud, no API keys, no telemetry — your conversations never leave your machine.
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](#privacy)
[](CONTRIBUTING.md)
</div>
---
## The problem
You solved that exact bug eight months ago. You worked out that architecture with
ChatGPT last spring. You had a long conversation about the deployment pipeline in
some Claude Code session you can no longer find.
All of it is sitting on your disk, in export files you never opened again. Your
assistant can't reach any of it, and neither can you — the built-in search in
Claude and ChatGPT is keyword-only and stops at the app boundary.
## The fix
`AI Memory MCP` ingests your conversation exports, chunks them, embeds them locally
with `all-mpnet-base-v2`, and stores the vectors in SQLite with
[`sqlite-vec`](https://github.com/asg017/sqlite-vec). Then it hands your assistant
five tools to search that history by **meaning**, not keywords.
```
You: What did we decide about the retry logic for the payment webhook?
Claude: [searches memory]
Found it — a Claude Code session from March 14th. You settled on
exponential backoff capped at 5 attempts, and explicitly rejected
a dead-letter queue because the provider already replays failures.
```
Ask in English about a conversation you had in Spanish. Ask about "the database
thing" and find the session where you never once wrote the word "database".
That's what semantic search buys you.
---
## Features
| | |
|---|---|
| **Three sources, one index** | Claude Desktop, ChatGPT and Claude Code, searched together |
| **Semantic, not keyword** | Finds meaning — 768-dim embeddings, cosine similarity |
| **Cross-lingual** | Query in one language, match conversations in another |
| **100% local** | Embeddings run on your CPU. Nothing is uploaded. No API key needed |
| **Zero infrastructure** | One SQLite file. No Docker, no Postgres, no vector service |
| **Fast cold start** | Model prewarms in a background thread; the MCP handshake never blocks |
| **Incremental ingest** | Re-run any time; already-indexed conversations are skipped |
---
## Quick start
### 1. Install
```bash
git clone https://github.com/optimaquantum/ai-memory-mcp.git
cd ai-memory-mcp
uv pip install -r requirements.txt
```
> Works with plain `pip install -r requirements.txt` too. First run downloads the
> ~420 MB embedding model once, then it is cached offline forever.
### 2. Get your conversations
| Source | How |
|---|---|
| **Claude Desktop** | Settings → Privacy → **Export Data** → you get an email → drop the ZIP in `imports/claude-desktop/` |
| **ChatGPT** | Settings → Data Controls → **Export Data** → you get an email → drop the ZIP in `imports/chatgpt/` |
| **Claude Code** | Nothing to do — read automatically from `~/.claude/projects/` |
### 3. Register the MCP server
Add to your `~/.claude.json` (Claude Code) or `claude_desktop_config.json`:
```json
{
"mcpServers": {
"ai-memory": {
"type": "stdio",
"command": "uv",
"args": ["--directory", "/absolute/path/to/ai-memory-mcp",
"run", "python", "-m", "src.server"]
}
}
}
```
### 4. Index everything
```bash
uv run python -m src.ingest
```
Or just ask your assistant to run `ingest_exports`. Done — start asking it what
you talked about.
### Optional: index Claude Code automatically as you work
`ingest_debounced.sh` keeps your Claude Code history current without you thinking
about it. Wire it to a Claude Code `Stop` hook and it re-indexes at most once
every 30 minutes, with a lock so two ingests can never overlap:
```json
{
"hooks": {
"Stop": [{ "hooks": [{ "type": "command",
"command": "/absolute/path/to/ai-memory-mcp/ingest_debounced.sh" }] }]
}
}
```
---
## Tools exposed to your assistant
| Tool | What it does |
|---|---|
| `search_memory` | Semantic search across all history. Filter by source, set a result limit |
| `get_conversation` | Pull one full conversation by ID, all chunks, in order |
| `list_conversations` | Browse and paginate, optionally filtered by source |
| `ingest_exports` | Index new export files without restarting anything |
| `memory_stats` | Conversation, chunk and embedding counts, plus database size |
---
## Privacy
This is the whole point, so it is worth being explicit.
- **Embeddings are computed locally** by `sentence-transformers` on your CPU. Your
conversation text is never sent to OpenAI, Anthropic, or anyone else.
- **No API keys.** The project has no network calls at query time at all.
- **No telemetry.** Nothing phones home. Read `src/` — it is about 1,200 lines.
- **Your data stays in one file** you control: `data/memory.db`. Delete it and the
memory is gone.
- The shipped `.gitignore` excludes `data/` and `imports/` precisely so you cannot
accidentally commit your own conversation history.
The only thing that ever touches the network is the one-time model download from
Hugging Face on first run.
---
## How it works
```
imports/*.zip ~/.claude/projects/
│ │
└──────────┬─────────────────────┘
▼
extractors/ parse each format into a common shape
▼
chunking ~500 tokens, split on message boundaries
▼
all-mpnet-base-v2 768-dim vectors, computed locally
▼
SQLite + sqlite-vec one file, cosine similarity
▼
MCP server 5 tools over stdio
```
**Technical details**
- Embedding model: `all-mpnet-base-v2` — 768 dimensions, strong on semantic
similarity benchmarks and genuinely multilingual in practice
- Chunking: ~500 tokens, `tiktoken` `cl100k_base`, respecting message boundaries
so a chunk never straddles two speakers
- Storage: SQLite with the `sqlite-vec` extension — vector search with no server
- Ingest is idempotent: conversations already indexed are skipped by ID
---
## Comparison
| | AI Memory MCP | Built-in Claude/ChatGPT search | Cloud vector DBs |
|---|---|---|---|
| Search type | Semantic | Keyword | Semantic |
| Cross-app history | ✅ | ❌ one app only | Depends |
| Works offline | ✅ | ❌ | ❌ |
| Data leaves machine | ❌ never | ✅ | ✅ |
| API key / subscription | None | — | Usually |
| Setup | One SQLite file | — | Service + schema + keys |
---
## FAQ
**Does this work with Cursor, Windsurf, Zed or other MCP clients?**
Yes. It is a standard stdio MCP server — anything that speaks MCP can use it.
**How big does the database get?**
Roughly 1 GB of raw exports lands around 300 MB indexed, embeddings included.
**How slow is ingesting?**
It is bound by embedding throughput on your CPU. Thousands of conversations take
a while the first time; after that it is incremental and quick.
**Can I use a different embedding model?**
Yes — change the model name in `src/embeddings.py`. Delete `data/memory.db` and
re-ingest afterwards, since vectors from two models are not comparable.
**Does it handle conversations in languages other than English?**
Yes, and it matches across them. Asking in English regularly surfaces the right
Spanish conversation.
---
## Contributing
Issues and PRs are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Good first
contributions: extractors for other assistants (Gemini, Copilot, Perplexity),
alternative embedding backends, and a proper test suite.
## License
[MIT](LICENSE) — do whatever you want with it.
---
<div align="center">
Built by **[Optima Quantum](https://optimaquantum.com)** — AI automation and
infrastructure engineering.
If this saved you from digging through a 1 GB export by hand, a ⭐ helps other
people find it.
</div>
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessNo issues