theseusmem-mcp
Provides optional local semantic vector retrieval via an Ollama endpoint, enabling embedding-based search when the service is online and falling back gracefully when offline.
Provides optional OpenAI-compatible embeddings for semantic vector retrieval, allowing the memory server to enhance hybrid search with external embedding models via a /v1 endpoint.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@theseusmem-mcp Search my memory for my preferred coding style"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TheseusMEM
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 optionalsource_agentattribution, enabling unified global recall or source-filtered lookup.Dual-Store + Entity Graph in One File: Persists structured long-term
facts(semantic layer), rawepisodes(episodic logs), and an entity relationship graph inside a single portable.dbfile.Four-Path Hybrid Retrieval: Blends SQLite FTS5 (
jiebaChinese 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.
Related MCP server: agent-memory-mcp
Quick Start
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):
{
"mcpServers": {
"theseusmem": {
"command": "theseusmem-mcp",
"env": {
"THESEUSMEM_DB_PATH": "~/.theseusmem/memory.db",
"THESEUSMEM_AGENT": "cursor"
}
}
}
}YAML MCP Config (CLI / Gateway Agents):
mcp_servers:
theseusmem:
command: theseusmem-mcp
env:
THESEUSMEM_DB_PATH: ~/.theseusmem/memory.db
THESEUSMEM_AGENT: chat-assistantMCP Tools Exposed
Tool | Purpose |
| Hybrid search across all agents' structured facts (supports optional |
| Hybrid search over raw episodic conversation turns |
| Algebraic HRR unbinding probe for all facts linked to an entity |
| Deduplicate and persist a durable fact with |
| Progressive reader/search over cold-layer Markdown files with |
| Inspect full metadata, list high-trust entries, or trace surrounding turns |
| Report store counts, cross-agent source breakdown, weights, and runtime dependencies |
Configuration (Environment Variables)
Variable | Default | Description |
|
| Shared SQLite memory database path |
|
| Caller agent tag for cross-agent attribution |
|
| Cold-layer Markdown reference directory |
| (unset) | Optional YAML domain dictionary for tokenization and synonym expansion |
|
| Optional OpenAI-compatible |
|
| Embedding model identifier |
|
| Set to |
License
MIT
Available Tools
9 toolsget_factB
Fetch full metadata and content for a single fact by fact_id.
Inputs: fact_id (required). Returns: result
get_timelineB
Fetch surrounding conversation turns around a given episode_id.
Inputs: episode_id (required), after, before. Returns: result
list_factsC
List high-trust facts filtered by optional category.
Inputs: limit, category, min_trust. Returns: result
memory_statsB
Return memory store statistics, cross-agent sources, weights, and dependency status.
Inputs: no named parameters. Returns: result
recall_entityC
Probe all facts associated with an entity using HRR algebraic unbinding.
Inputs: entity (required), limit. Returns: result
remember_factB
Deduplicate and persist a durable fact, preference, or decision into the shared store.
Tags the entry with source_agent (or THESEUSMEM_AGENT) for cross-agent attribution.
Inputs: content (required), tags, category, trust_score, +1 more. Returns: result
search_episodesB
Search raw episodic conversation turns (FTS5 + synonym expansion + optional vectors).
Inputs: query (required), limit, session_id. Returns: result
search_factsB
Search structured long-term facts across all connected agents.
Uses multi-path hybrid retrieval (FTS5 + jieba + Jaccard + HRR + optional embeddings + entity graph). Optionally filter by category or source_agent (e.g. "claude-code", "cursor").
Inputs: query (required), limit, category, source_agent. Returns: result
search_referenceC
Progressive reader/search over cold-layer Markdown files in THESEUSMEM_REFERENCE_DIR.
Inputs: query, filename. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Related MCP Connectors
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceLocal, cross-agent memory for AI coding agents using a single SQLite file, enabling persistent sessions and durable facts shared across multiple MCP-compatible tools.10 npmMIT
- AlicenseBqualityBmaintenanceLocal long-term memory service for AI agents via MCP, using SQLite with tools for memory CRUD, semantic search, time-based facts, and graph capabilities.2720 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to store and recall durable facts, decisions, and lessons over MCP using hybrid semantic and keyword search, typed memories, graph relations, sessions, and time-travel queries. Runs locally with no server process or API key, persisting everything to files that both agents and a CLI can share.28 npmMIT
- AlicenseBqualityCmaintenanceEnables multiple AI agents and harnesses to share one local SQLite-backed memory store over standard MCP, so decisions, preferences, and past pitfalls carry across sessions instead of being re-explained. Runs fully offline with local Chinese-capable search, zero dependencies, and no accounts, API keys, or telemetry.11MIT