theseusmem-mcp
# TheseusMEM
[中文文档](README_zh.md)
**One memory keel. Every AI agent you use.**
You switch editors, try new coding assistants, and spin up fresh chat agents. Each time the shell changes, your context resets to zero, leaving preferences, decisions, and hard-won lessons scattered across incompatible silos.
**TheseusMEM** solves this with the *Ship of Theseus* principle: replace the planks, swap the sails, change the agent frontend as often as you like, while keeping one continuous, portable memory keel underneath. Built in ~2,200 lines of clean Python on a single SQLite file, it runs locally with zero Docker containers and zero external database daemons.
## What Makes It Different
* **Cross-Agent Memory Continuity**: Multiple MCP clients (IDEs, CLI agents, desktop chat apps) connect concurrently via SQLite WAL mode to the same `memory.db`. Every stored fact carries optional `source_agent` attribution, enabling unified global recall or source-filtered lookup.
* **Dual-Store + Entity Graph in One File**: Persists structured long-term `facts` (semantic layer), raw `episodes` (episodic logs), and an entity relationship graph inside a single portable `.db` file.
* **Four-Path Hybrid Retrieval**: Blends SQLite FTS5 (`jieba` Chinese tokenization + English), Jaccard lexical overlap, Holographic Reduced Representations (HRR) phase vectors for algebraic reasoning (`probe`, `related`, `reason`, `contradict`), and optional OpenAI-compatible embeddings.
* **Zero-Daemon Circuit Breaker**: Need local semantic vectors from an Apple Silicon MLX server or Ollama? TheseusMEM probes the endpoint in `0.3s`, activates 1024-dim vector retrieval when online, and falls back gracefully with zero blocking when offline.
* **Tiered Biological Decay**: Core memory categories (`identity`, `rule`, `preference`, `core`, `psychology`, `academic`) and high-trust entries (`>= 0.75`) never fade, while transient observations decay naturally with a 30-day half-life.
## Quick Start
```bash
pip install -e .
```
### Wire All Your Agents to One Shared Keel
Point different MCP clients to the same `THESEUSMEM_DB_PATH` and tag each with its own `THESEUSMEM_AGENT`:
**JSON MCP Config (Cursor / Claude Desktop / IDE Copilots):**
```json
{
"mcpServers": {
"theseusmem": {
"command": "theseusmem-mcp",
"env": {
"THESEUSMEM_DB_PATH": "~/.theseusmem/memory.db",
"THESEUSMEM_AGENT": "cursor"
}
}
}
}
```
**YAML MCP Config (CLI / Gateway Agents):**
```yaml
mcp_servers:
theseusmem:
command: theseusmem-mcp
env:
THESEUSMEM_DB_PATH: ~/.theseusmem/memory.db
THESEUSMEM_AGENT: chat-assistant
```
## MCP Tools Exposed
| Tool | Purpose |
| :--- | :--- |
| `search_facts` | Hybrid search across all agents' structured facts (supports optional `category` and `source_agent` filters) |
| `search_episodes` | Hybrid search over raw episodic conversation turns |
| `recall_entity` | Algebraic HRR unbinding probe for all facts linked to an entity |
| `remember_fact` | Deduplicate and persist a durable fact with `source_agent` attribution |
| `search_reference` | Progressive reader/search over cold-layer Markdown files with `[[wikilink]]` extraction |
| `get_fact` / `list_facts` / `get_timeline` | Inspect full metadata, list high-trust entries, or trace surrounding turns |
| `memory_stats` | Report store counts, cross-agent source breakdown, weights, and runtime dependencies |
## Configuration (Environment Variables)
| Variable | Default | Description |
| :--- | :--- | :--- |
| `THESEUSMEM_DB_PATH` | `~/.theseusmem/memory.db` | Shared SQLite memory database path |
| `THESEUSMEM_AGENT` | `default` | Caller agent tag for cross-agent attribution |
| `THESEUSMEM_REFERENCE_DIR` | `~/.theseusmem/reference` | Cold-layer Markdown reference directory |
| `THESEUSMEM_DICT_PATH` | *(unset)* | Optional YAML domain dictionary for tokenization and synonym expansion |
| `THESEUSMEM_EMBED_URL` | `http://127.0.0.1:7861/v1` | Optional OpenAI-compatible `/v1` embeddings endpoint |
| `THESEUSMEM_EMBED_MODEL` | `Qwen/Qwen3-Embedding-0.6B` | Embedding model identifier |
| `THESEUSMEM_READ_ONLY` | `0` | Set to `1` to disable `remember_fact` writes |
## License
MIT
TDQS
Scored across 9 tools
Most tools target distinct resources: facts, episodes, entities, timelines, reference files, and stats. However, search_facts, list_facts, and recall_entity all return facts and could be confused without careful reading; descriptions partially clarify the boundaries.
Nearly all tools use a consistent snake_case verb_noun pattern (search_facts, get_fact, remember_fact, etc.). memory_stats is the main deviation, using a noun phrase instead of a verb, but overall the naming is predictable.
Nine tools is well-scoped for a memory server, covering search, retrieval, persistence, entity recall, timelines, references, and stats. Each tool appears to earn its place without obvious redundancy.
The server covers creation and rich read paths for facts, episodes, and references, but lacks explicit update, delete, or forget operations. For a long-term memory store, the absence of deletion/forgetting and episode write operations is a notable lifecycle gap.