Mnemosyne — the Greek goddess of memory: memory never dies, is always
reconstructable, and persists across sessions.
Compile any long-term interaction into an evolving human cognitive model: identity, preference, goal, emotion, relationship. Designed for companion AIs to maintain consistent persona across sessions.
LLM-free memory distillation engine + MCP server for companion AIs. Compiles conversations into cognitive facts, keeps persona consistent across sessions. No API key, no LLM guessing.
Sterne
4
Tools
—
Uptime
—
Facts come from compilation, not guesswork.State comes from events, not prompts.Long-term cognition comes from the model, not context window length.
About the Name
Mnemosyne is the Greek goddess of memory — mother of the nine
Muses, keeper of everything that must not be forgotten. The name is a promise
made concrete by this engine:
Memory never dies — facts are persisted in SQLite and survive
across sessions, independent of the context window; memory_export/memory_import
back them up and move them between machines intact.
Reconstructable — every fact carries an evidence chain
(EvidenceRef) and a scoring rule, so a persona's evolution timeline can be
rebuilt from raw history at any time — nothing is guessed, everything is
traceable.
Continuity across sessions — cognition is in the model,
not in the prompt: the store, not the context window, is the source of truth.
Just as Mnemosyne let poets and heroes remember, this engine lets a companion
AI remember its user — deterministically, without an LLM in the loop.
Proactive context-aware distillation: above threshold auto-compiles the conversation into facts + long-term memories + user profile; below threshold it is a read-only diagnostic
Record Agent feedback on memories (for self-evolution)
memory_id
memory_stats
Tenant-level memory statistics
—
memory_decay
Deterministic memory decay/forgetting (down-weight + archive stale facts, never deletes)
—
Knowledge Ingestion / External Source Tools
Tool
Function
Required Params
generalize_compile
Compile ANY external data (pasted conversation doc_type=dialog or raw prose doc_type=text) into the unified knowledge graph (documents/entities/edges/evidence)
messages[] or text
agent_fact_compile
Compile AI conversation into three-state facts (support/contradict/unrelated)
messages[]
knowledge_attach
Attach an external knowledge source (PDF/JSON/TXT/MD documents or JSON-backed DBs) as a searchable adapter
source_name, path
knowledge_ingest
Materialize an attached external source into the knowledge graph as documents + chapters + evidence
source_name
memory_export
Serialize the whole knowledge graph into a portable JSON snapshot (inline or to path)
—
memory_import
Replay a memory_export snapshot back into the store, deduplicating by identity
Distill a person's trajectory into key events (score + evidence)
name
search_graph
Structured graph search by name substring / object type / attribute value, scoped by document
query
trace_path
Shortest relationship path between two named entities (BFS over graph edges)
source, target, max_depth
Companion Persona Tools
Persona-consistency tools for companion AIs (keeping the persona stable across
sessions): inject a structured
persona card, guard a draft reply against the stored persona, track the agent↔user
relationship, and rebuild the persona's evolution timeline.
Tool
Function
Required Params
persona_inject
Inject a structured, deterministic persona card (identity / persona / style / taboos / relationship) into the system prompt; multi-tenancy by tenant_id
agent_id
persona_check
Guard the agent's draft reply against the accumulated persona facts; report conflicts + drift (no LLM, keyword fallback)
agent_id, draft
relationship_update
Incrementally update the agent↔user relationship state from message emotion signals (intimacy / stage / trend / recent topics)
agent_id, user_id, messages[]
relationship_query
Read the current relationship snapshot for a tenant/agent/user triple
agent_id, user_id
persona_timeline
Rebuild an entity's persona evolution timeline (origin → turning point → current state) from accumulated facts (mem0 v3 ADD-only)
entity_id
story_bridge
Novel-character bridge: compile a protagonist's knowledge-graph story events into fact-store persona facts, providing cold-start baseline for persona_timeline/persona_check
name
memory_decay
Deterministic memory decay / forgetting: down-weight and archive stale facts, never delete (protects high-value persona facts)
—
V1 Legacy Character Tools
Tool
Function
Note
character_search
Search characters by name/attribute/novel
Read-only after migration; based on old character_* tables
character_network
Character relation graph BFS
Read-only after migration
character_ingest
Run four classics corpus distillation pipeline
Triggers full V1 extraction
character_graph
Export 3D character relation graph JSON
For visualization
portrait_extract (resume → person portrait) was removed in favor of the
cognition-Facts conversation pipeline, which is the supported path for
companion-AI persona profiling.
Semantic Similarity Without an LLM
The system is deliberately LLM-free for retrieval and persona reasoning: all
semantic approximation is done with deterministic, offline algorithms, so the
server has zero API-key dependency and its behavior is reproducible across
runs. The techniques, in order of increasing semantic reach:
1. Keyword matching — FTS5
MEMORY_VECTOR_DIM=0 (the default) enables SQLite FTS5 keyword search with
proper Unicode handling and escaped LIKE wildcards. Exact and substring
matches are answered directly from the index — O(log n), no embedding needed.
2. Vector retrieval — cosine similarity
When MEMORY_VECTOR_DIM>0 and an embedding provider is configured
(MEMORY_EMBEDDING_PROVIDER=openai|ollama, a remote API), text is embedded
and queried by cosine similarity:
brute_force.rs — exact O(N) full scan (the ground truth);
hnsw.rs — approximate nearest neighbor for large graphs, with an agreed
convention on degenerate inputs: a zero vector returns distance sqrt(2)
(cosine = 0.0), identical to the brute-force scan, so both indexes agree.
3. Hybrid retrieval
MEMORY_RETRIEVAL_MODE=hybrid merges keyword hits and vector hits; results
without a vector (e.g. legacy rows) fall back to keyword-only scoring, so the
retrieval path never silently drops entries that lack an embedding.
4. Character-bigram Jaccard for names & aliases
For entity-name matching (compiler/resolver.rs) each name is embedded as its
set of character bigrams (e.g. 张三 → {张三}; 张飞 → {张飞}), and
similarity is the Jaccard overlap of the two bigram sets — no vector model
required. This catches transliteration/copy errors and partial-name aliases
deterministically.
5. Shared-bigram heuristics for persona consistency
persona_check (no-LLM path) compares a draft reply against stored persona
facts with negation detection + shared-bigram overlap: two statements
about the same bigram topic are flagged as conflict/drift without any model —
我讨厌应酬 vs 我喜欢安稳 are correctly not marked as a stance flip
because they share fewer than 2 bigrams.
6. Rule-driven compilation
The whole extraction pipeline is rules, not inference: Aho-Corasick verb
matching (observation_compiler), deterministic event/relation builders
(compiler/extract.rs, timeline.rs), key-event importance scoring
(evidence richness + participant centrality + turning-point flag), and
rule-based relationship state updates (relationship_update) all run offline
and are fully reproducible.
Net effect: every fact, edge, and retrieved result carries a traceable
evidence chain or scoring rule — the "no LLM guessing" guarantee from
Core Principles holds end to end.
IDE Integration (MCP)
The server speaks standard MCP over stdio (or HTTP+SSE), so it plugs into any
IDE/agent that supports MCP clients — Claude Desktop, Cursor, VS Code,
JetBrains, or a custom agent framework.
Tip: cargo run compiles on first connect. For a snappy IDE experience
build once (cargo build --release) and point command at
target/release/mnemosyne with args: ["serve"].
HTTP+SSE (remote, requires token)
The HTTP transport exposes two endpoints: GET /sse (Server-Sent Events
stream) and POST /message (JSON-RPC). Configure the MCP client with the SSE
endpoint URL:
HTTP serving refuses to start without --http-token (see
Configuration); each concurrent client should send a stable
x-mcp-session-id so its SSE stream only receives its own responses. For
remote deployments use https:// — the bearer token would otherwise travel in
cleartext.
What the AI can do once connected
Distill the current conversation: the host passes the ongoing messages[]
to memory_compile / memory_context_check and gets structured facts,
decisions, session state and (optionally) long-term distilled memories —
persisted to SQLite for cross-session continuity.
Query the knowledge graph: inspect_entity, timeline, relation_graph,
search_graph, trace_path, evidence.
Guard persona consistency: persona_check / persona_inject /
relationship_update keep a companion AI's persona from drifting.
Note: MCP tools are called by the host — the server never auto-reads the
conversation. To auto-distill every turn, instruct the host (system prompt or
post-turn hook) to invoke memory_compile with the current messages.
Installation
Option 1 — Install script (recommended)
scripts/install.sh detects your platform/architecture, downloads the
matching release archive, and unpacks it into a .mnemosyne/ directory:
# macOS / Linux (bash)
curl -fsSL https://raw.githubusercontent.com/Timwood0x10/Mnemosyne/main/scripts/install.sh | bash
# Or clone and run it locally
git clone https://github.com/Timwood0x10/Mnemosyne.git
cd Mnemosyne
./scripts/install.sh # latest release
./scripts/install.sh v0.1.2 # a specific version
What it produces — everything lives in one directory, so the binary always
finds its resources next to itself:
~/.mnemosyne/
├── mnemosyne # the binary (mnemosyne.exe on Windows)
├── markers_zh.json # Chinese observation-marker word list (editable)
└── markers_en.json # English observation-marker word list (editable)
Run it:
~/.mnemosyne/mnemosyne serve
Option 2 — Manual download
Download the archive for your platform from the
Releases page:
Platform
Archive
macOS (Apple Silicon)
mnemosyne-aarch64-apple-darwin.tar.gz
macOS (Intel)
mnemosyne-x86_64-apple-darwin.tar.gz
Linux (arm64)
mnemosyne-aarch64-unknown-linux-gnu.tar.gz
Linux (x86_64)
mnemosyne-x86_64-unknown-linux-gnu.tar.gz
Windows (x86_64)
mnemosyne-x86_64-pc-windows-msvc.tar.gz
# macOS / Linux
mkdir -p ~/.mnemosyne && tar -xzf mnemosyne-<platform>.tar.gz -C ~/.mnemosyne
chmod +x ~/.mnemosyne/mnemosyne
~/.mnemosyne/mnemosyne --version
# Windows: extract with your archive tool, then run mnemosyne.exe
Customizing the marker word lists
markers_zh.json and markers_en.json decide which words in a conversation
produce facts. Each file maps an action (feel, plan, want, dislike,
belief, stuck, life_event, …) to a list of trigger words. Edit them to:
add your own vocabulary (modern slang, domain terms, personal quirks);
remove words that cause false positives;
tune what the engine extracts about the user.
No recompile needed — just edit the JSON and restart. If the files are absent
the binary falls back to built-in defaults.
Option 3 — Build from source
Requires a Rust toolchain (see rust-toolchain / Cargo.toml for the MSRV).
git clone https://github.com/Timwood0x10/Mnemosyne.git
cd Mnemosyne
cargo build --release
./target/release/mnemosyne --version
# Zero config: SQLite only, no API key needed
cargo run --bin mnemosyne \
--embedding-provider none \
--retrieval-mode keyword \
--db-path ./knowledge.db
CLI Commands
Command
Description
serve (default)
Start MCP stdio server
ingest --corpus-dir corpus
Run V1 corpus distillation pipeline
migrate --corpus-dir corpus
Migrate V1 → General knowledge model
Testing
make check # cargo clippy + cargo check (0 error, 0 warning)
make test # 700+ unit + integration tests (nextest, ~18s)
# Full Romance of the Three Kingdoms compilation test
cargo test --test sanguo_compile e2e_sanguo -- --nocapture
Test Corpora
All test corpora live in corpus/ (text, PDF and dialog-JSON), with per-novel
entity profile packs in config/entity_profiles/.
Corpus
Language
Kind
Used by
三国演义.txt (Romance of the Three Kingdoms)
zh
novel text
sanguo_compile, generalize_corpus_regression
水浒传.txt (Water Margin)
zh
novel text
generalize_corpus_regression
红楼梦.txt (Dream of the Red Chamber)
zh
novel text
honglou_compile, generalize_corpus_regression
西游记.txt (Journey to the West)
zh
novel text
xiyou / generalize_corpus_regression
封神演义.txt (Investiture of the Gods)
zh
novel text
fengshen_*, generalize_corpus_regression
大秦帝国.txt (The Qin Empire)
zh
novel text
daqin
倾城之恋.txt (Love in a Fallen City)
zh
novella text
qingcheng / persona
WarandPeace.txt (War and Peace)
en
novel text (84k sentences)
war_peace, war_mcp (sampled: opening 100k chars)
PrideAndPrejudice.txt
en
novel text
generalize_corpus_regression
巴黎圣母院.pdf (Notre-Dame de Paris)
zh
PDF
e2e PDF (skipped if absent)
2.pdf
—
PDF
e2e PDF (skipped if absent)
bailiusu_escape.json (Bai Liusu flees the Bai household)
zh
dialog
caoren_*, companion MCP loop
warpeace_pierre.json (War and Peace · Pierre)
en
dialog
companion MCP loop
raskolnikov_porfiry.json
zh
dialog
generalize_corpus_regression (dialog path)
sonia_raskolnikov.json
zh
dialog
generalize_corpus_regression (dialog path)
conversation_export_2026-08-02.json
zh
dialog export
memory/migration tests
ques.json
zh
dialog
auxiliary
Entity profile packs (config/entity_profiles/): sanguo.json, shuihu.json,
honglou.json, xiyou.json, fengshen.json, warandpeace.json — each maps
the novel's canonical entity names/aliases for the compiler's dictionary
(JsonEntityProvider).
Slow full-corpus runs (e.g. the 7-novel generalize_corpus_regression) are
#[ignore]d by default; run them explicitly with --ignored.
Configuration
Env Var
Default Value
Description
MEMORY_DB_PATH
./memory.db
SQLite database path
MEMORY_VECTOR_DIM
0
0 = pure keyword (FTS5), >0 = vector search
MEMORY_EMBEDDING_PROVIDER
none
none / openai / ollama
MEMORY_RETRIEVAL_MODE
keyword
keyword / vector / hybrid
FACTION_MAP_PATH
config/faction_map.json
Faction map configuration
Development
make check # cargo clippy + cargo check
make test # All 320+ tests
make fmt # Format code
LLM-free memory distillation engine + MCP server for companion AIs. Compiles conversations into cognitive facts, keeps persona consistent across sessions. No API key, no LLM guessing.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Mnemosyne?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Mnemosyne einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet Mnemosyne?
Mnemosyne läuft lokal über stdio.
Wann wurde Mnemosyne zuletzt geprüft?
Zuletzt geprüft: 2026-10-28. LLM-free memory distillation engine + MCP server for companion AIs. Compiles conversations into cognitive facts, keeps persona consistent across sessions. No API key, no LLM guessing.