mnemos-dev 0.3.3

Obsidian-native AI memory palace with semantic search

Mnemos

Turn your Claude Code history into a searchable memory palace.

Every conversation becomes markdown in your Obsidian vault. Every decision stays findable. Your AI finally remembers you.

📖 Project Status — what works today vs. what's coming · 🗺️ Roadmap — the single canonical plan · 🤝 Contributing — dev setup + conventions

---

The Problem

You've had hundreds of Claude Code sessions. Decisions, debugging notes, hard-won context — all locked in ~/.claude/projects/*.jsonl files nobody ever opens again. Every new session starts from zero.

What Mnemos Does

Mnemos turns that history into a memory palace any future Claude Code session can search:

1. Refine — a bundled Claude Code skill reads your JSONL transcripts and writes focused session notes (decisions, outcomes, open questions) into your Obsidian vault. High signal, no tool noise.
2. Mine — regex + optional LLM extraction pulls individual memories out of those notes and classifies them by project, topic, and type.
3. Recall — 8 MCP tools let any Claude Code / Cursor / ChatGPT session search, graph, and load relevant context.

Storage is plain markdown in your vault. You read it, edit it, organize it. Two swappable vector backends index it for semantic search — ChromaDB (default, mature) or sqlite-vec (single-file, robust on Windows/Python 3.14). A 2026-04-17 parity benchmark showed they produce identical recall; switch any time with mnemos migrate --backend <name>. Obsidian is the source of truth — delete a note in Obsidian and the memory is gone.

Quick Start

# 1. Install
pip install mnemos-dev

# 2. Scaffold your vault — interactive wizard:
#    discovers Claude Code transcripts + vault Sessions/memory/Topics,
#    asks [A]ll / [S]elective / [L]ater, then mines what you choose.
#    Resumable via .mnemos-pending.json. TR + EN.
mnemos init

# 3. Install the refinement skill (one-time)
#    Windows:
mklink /J "%USERPROFILE%\.claude\skills\mnemos-refine-transcripts" \
  "<mnemos-repo>\skills\mnemos-refine-transcripts"
#    macOS / Linux:
ln -s <mnemos-repo>/skills/mnemos-refine-transcripts \
  ~/.claude/skills/mnemos-refine-transcripts

# 4. Wire it to Claude Code
claude mcp add mnemos -- python -m mnemos --vault /path/to/your/vault

# 5. In a Claude Code session:
/mnemos-refine-transcripts --limit 5   # pilot: 5 JSONLs → Sessions/
mnemos mine Sessions/                   # extract memories into the palace

Or skip the manual flow above and let mnemos init walk you through everything. Add sources later with mnemos import claude-code, mnemos import chatgpt <export.json>, etc.

After init, every new Claude Code session automatically refines + mines the most recent closed transcripts in the background (via a SessionStart hook installed by mnemos init). The statusline shows a one-shot snapshot at session start; check <vault>/.mnemos-hook.log for detailed progress. Open sessions are protected — PID-based markers ensure no transcript is refined while its window is still active.

Future Claude Code sessions automatically pull context via mnemos_wake_up + mnemos_search.

The Refinement Skill

skills/mnemos-refine-transcripts/ ships with the repo. After the symlink/junction above, Claude Code sees it as /mnemos-refine-transcripts. The skill:

• Discovers JSONL transcripts under ~/.claude/projects/
• Runs a prose extractor (drops tool calls, hooks, sidechains)
• Applies the canonical refinement prompt at docs/prompts/refine-transcripts.md — one source of rules, no drift
• Writes value-carrying sessions to <vault>/Sessions/<YYYY-MM-DD>-<slug>.md, skips noise
• Keeps a local ledger (skills/mnemos-refine-transcripts/state/processed.tsv) so nothing gets reprocessed
• Pilots 5 at a time before committing to the full batch

The skill does not call any LLM API — it runs inside your existing Claude Code session. Zero additional cost, zero extra dependencies.

Migrating from older session-memory setups

If you were an early adopter and your ~/.claude/ still has any of these, they are now superseded by the auto-refine hook installed by mnemos init and can be removed safely:

• ~/.claude/skills/session-memory/ — pre-mnemos manual SAVE-on-keyword skill. The auto-refine hook captures every transcript automatically; no need to type "bye" / "kaydet" anymore. Delete the folder.
• ~/.claude/hooks/mnemos-session-mine.py (and its mnemos-mine-worker.py / mnemos-mined-transcripts.json / mnemos-mine.lock siblings) — the original raw-transcript miner. Replaced by the refine-then-mine pipeline (refining drops 99% of tool noise before mining). Delete those files and remove the matching SessionStart entry from ~/.claude/settings.json (keep only the entry whose _managed_by is mnemos-auto-refine).

Mnemos itself doesn't auto-delete user files — these are one-time manual cleanups.

Why Not Just Raw Transcripts?

	Raw JSONL	Refined Sessions/
Size	50-500 KB each, 99% tool noise	10-50 lines of actual decisions
Searchability	Semantic search drowns in tool calls	Every hit is a real turn
Readability	JSON blobs	Human markdown
Portability	Claude Code format only	Markdown, any tool

Refinement is selective: curated .md files (memory, Topics/, hand-written Sessions/) skip refinement and are mined directly. Noisy sources (JSONL, email, PDF) get refined first.

How It Works

Mnemos uses a Memory Palace architecture inspired by the ancient Greek method of loci:

Your Obsidian Vault
  +-- Mnemos/
      +-- Wings/              (projects & people)
      |   +-- ProjectA/
      |   |   +-- auth/           (topic rooms)
      |   |   |   +-- decisions/      (memory types)
      |   |   |   +-- facts/
      |   |   |   +-- problems/
      |   +-- ProjectB/
      +-- Identity/           (who you are - L0)
      +-- _recycled/          (soft-deleted memories)

Every memory is a .md file with YAML frontmatter. Two backends ship behind the same interface: ChromaDB (default) or sqlite-vec. Pick one during mnemos init, or swap later with mnemos migrate --backend sqlite-vec. If it's not in your vault, it doesn't exist.

MCP Tools

Tool	Description
mnemos_wake_up	Session startup context (~200 tokens: identity + wings)
mnemos_search	Semantic search with wing/room/hall filters + dual collection (raw/mined/both)
mnemos_recall	Load context (L0 identity, L1 summaries, L2 details)
mnemos_add	Add a new memory
mnemos_mine	Extract memories from files or directories
mnemos_graph	Query entity relationships
mnemos_timeline	Chronological entity history
mnemos_status	Palace statistics

Works with Claude Code, Cursor, ChatGPT, and any MCP-compatible client.

Mining

Mnemos extracts memories using a 10-step pipeline:

1. Format detection — Claude Code JSONL, ChatGPT JSON, Slack JSON, or plain markdown
2. Conversation normalization — chat exports → standard transcript format
3. Prose extraction — filters code blocks, shell commands, non-human text
4. Exchange-pair chunking — keeps questions and answers together
5. Room detection — 72+ folder/keyword patterns across 13 categories
6. Entity detection — heuristic person/project classification
7. 172 regex markers — 87 English + 85 Turkish across 4 halls (decisions, preferences, problems, events)
8. Scoring + disambiguation — confidence-based classification
9. Claude API (optional) — catches what regex misses, works in any language

mnemos mine Sessions/                                  # the usual flow
mnemos mine ~/chatgpt-export.json                      # auto-detected format
mnemos mine Sessions/ --rebuild                        # wipe & re-index
pip install mnemos-dev[llm] && mnemos mine Sessions/ --llm   # LLM-assisted

Conversation Formats

Format	Source	Auto-detected
Claude Code JSONL	~/.claude/projects/*/conversations/	✅
Claude.ai JSON	claude.ai export	✅
ChatGPT JSON	chatgpt.com export	✅
Slack JSON	Slack workspace export	✅
Plain text / Markdown	Any .md or .txt	✅

External Sources (Read-Only)

mnemos mine ~/some/notes --external

External sources are mined once. Source files are never modified or watched.

File Watcher

Changes you make in Obsidian sync to the vector index automatically:

Action	Result
Add a note	Indexed
Edit a note	Re-indexed
Delete a note	Removed from index
Move a note	Metadata updated

Runs inside the MCP server. Detects offline changes on restart.

Memory Stack (L0–L3)

Efficient context loading — your AI knows you without burning tokens:

Level	Content	Tokens	Loaded
L0	Identity	~50	Every session
L1	Wing summaries	~150	Every session
L2	Room details	~300–500	When topic mentioned
L3	Deep search	~200–400	When asked

Configuration

mnemos.yaml in your vault root:

version: 1
vault:
  path: "/path/to/your/vault"
mining:
  languages: [tr, en]
  use_llm: false
  sources:
    - path: "Sessions/"
      mode: sessions
    - path: "Topics/"
      mode: general
halls:
  - decisions
  - facts
  - events
  - preferences
  - problems

Troubleshooting

Which backend am I on?

mnemos status

The first line tells you — e.g.

Backend: sqlite-vec (search.sqlite3 · 8027 drawers · 42.3 MB)

ChromaDB index corruption or errors

If mnemos search / mnemos mine fails with an HNSW / DatabaseError / segfault-style message from ChromaDB, the single recovery command is:

mnemos migrate --backend sqlite-vec

This backs up the broken .chroma/ directory (date-stamped, never overwritten), updates mnemos.yaml, and rebuilds the index from your vault's Sessions/ + Topics/ + memory/ folders. No memories are lost — your .md files are the source of truth. Run --dry-run first if you want to see the plan without changing anything:

mnemos migrate --backend sqlite-vec --dry-run

mnemos init and every runtime error path also suggest this command, so a user seeing an unfamiliar traceback has an actionable recovery line.

Switching back to ChromaDB

Same command, other way around:

mnemos migrate --backend chromadb

Backups are kept under <palace>/.chroma.bak-YYYY-MM-DD/ and <palace>/search.sqlite3.bak-YYYY-MM-DD — delete them manually when you're confident the new backend is good.

Architecture

Claude Code / Cursor / ChatGPT
        |
        | MCP (stdio)
        v
  +------------------+
  |  Mnemos Server   |
  |  (8 MCP tools)   |
  +-----|------|------+
        |      |
   ChromaDB   SQLite
   (or        (knowledge graph)
   sqlite-vec)
    |    |
  raw  mined       ← Reciprocal Rank Fusion merge
    |    |
    v    v
  +-----------------------+
  |   Obsidian Vault      |
  |   (.md files = truth) |
  +-----------------------+

Benchmarks

Mnemos uses LongMemEval (500 questions across 54 conversation sessions) for recall measurement.

pip install mnemos-dev[benchmark]
mnemos benchmark longmemeval              # all 500 questions
mnemos benchmark longmemeval --limit 10   # quick smoke
mnemos benchmark longmemeval --mode raw-only

Mode	Description
raw-only	Verbatim collection only
mined-only	Classified collection only
combined	Both, with RRF merge (default)

Roadmap

• v0.1 — Core palace architecture, 8 MCP tools, basic regex mining
• v0.2 — Dual collection, 5 conversation formats, 172 markers, LongMemEval benchmark harness
• v0.3 — First-run experience ✅ released: refine-transcripts skill, .mnemos-pending.json resume mechanism, mnemos init 5-phase discover/classify/import wizard, mnemos import {claude-code,chatgpt,slack,markdown,memory} subcommand family, CLI i18n (TR + EN), CONTRIBUTING.md, SessionStart auto-refine hook (mnemos install-hook), mnemos install-statusline, no-flicker / no-mid-conversation-refire fixes, legacy session-memory deprecation guide, new-user simulation pilot.
• v0.3.1 — Backend UX ✅ released: mnemos init backend picker (ChromaDB / sqlite-vec), mnemos migrate --backend <name> with dry-run + dated backups, BackendInitError with migrate recipe, mnemos status backend summary line, README Troubleshooting recipes.
• v0.3.2 — Palace Hygiene ✅ released: TR-aware wing canonicalization, lazy hall / _wing.md / _room.md creation, source-date filenames + H1+wikilink drawer bodies, entity hygiene (no tags, case-preserve dedup), atomic mnemos mine --rebuild (backup → drop+reinit → re-mine → verify → rollback), distribution-ready memory-source handling (additive _resolve_sources, yaml persistence on import).
• v0.4 — AI engine: Claude API mining quality pass, reranking, contradiction detection
• v0.5 — Automation: session hooks, memory lifecycle, knowledge graph deepening
• v0.6 — Ecosystem: specialist agents, multi-source connectors, Obsidian plugin

vs. MemPalace

MemPalace proved structured memory architecture works for AI. Mnemos takes the same idea and makes it Obsidian-native and Claude Code-first.

	MemPalace	Mnemos
Storage	ChromaDB binary (opaque)	Obsidian markdown (you can read it)
Mining	English regex only	Hybrid: regex + Claude API (any language)
Primary source	Generic strings	Claude Code JSONL via refinement skill
Access	AI only	You AND your AI
Deletion	API call	Delete in Obsidian, auto-synced
Ecosystem	Standalone	Obsidian Graph View, Dataview, plugins

Contributing

git clone https://github.com/mnemos-dev/mnemos.git
cd mnemos
pip install -e ".[dev,llm]"
pytest tests/ -v

Built from scratch (not a fork) — inspired by MemPalace's palace architecture.

License

MIT — Copyright 2026 Tugra Demirors / GYP Energy