Skip to main content
Glama
README.md
# 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

B3.1/5.0

Scored across 9 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness3/5

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.