Skip to main content
Glama

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 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.

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-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

Available Tools

9 tools
get_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

    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.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Local, 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 npm
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Local long-term memory service for AI agents via MCP, using SQLite with tools for memory CRUD, semantic search, time-based facts, and graph capabilities.
      27
      20 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      11
      MIT