🚧 Alpha — APIs, defaults, and on-disk config surfaces may still change between 0.x releases. Feedback and issue reports are especially welcome at github.com/memtomem/memtomem/issues.

Markdown-first long-term memory infrastructure for AI agents. Core usage is hook-free by default: your files remain the source of truth, and memory changes happen only when you or your agent explicitly call memtomem. Optional client hooks are separate, visible integrations.

Core philosophy: .md files are the source of truth and the vector database is a derived cache. Manage memories as plain text files — memtomem makes them instantly searchable.

Built for:

AI agents (Claude Code, Cursor, Windsurf, Claude Desktop, Kimi CLI) that need to remember between sessions
Developers who want a searchable knowledge base built from their existing markdown notes — no proprietary database, no vendor lock-in
Multilingual content (English, Korean, Japanese, Chinese) via local multilingual-e5-small embeddings, the ONNX default (bge-m3 remains available)

Quick Start

# 1. Install memtomem with all features (Python 3.12+)
uv tool install 'memtomem[all]'  # or: pipx install 'memtomem[all]'
mm --version

# 2. Configure storage, search, and optional MCP registration
mm init

# 3. Verify a complete memory round trip
mm status
mm add "Deployment checklist uses blue-green rollout" --tags ops
mm search "blue-green"

The search should return the sentence you just added. mm add writes to your configured user memory directory and indexes the entry immediately, so this path works without an existing notes directory or a connected editor.

Choose Minimal in the setup picker for a no-model-download first proof; rerun mm init later to add semantic search.

To index existing files next:

mm index /path/to/your/notes

If mm init registered an MCP client, ask it to Call the mem_status tool. See Getting Started for install alternatives, the Korean Claude Code/Codex quickstart for a plugin-first path, and MCP Client Setup for manual registration.

[all] includes ONNX, Ollama and OpenAI integrations, Korean tokenization, code chunking, the Web UI, Langfuse tracing, and LangGraph Store support. Install bare memtomem for BM25-only usage. See the optional extras table for smaller bundles. If mm is not on PATH, run uv tool update-shell and open a new shell. If an install appears stale, re-run it with --refresh.

memtomem is the long-term-memory store. memtomem-stm is a separate, optional MCP proxy for automatic surfacing, compression, and caching.

Key Features

🔍 Hybrid search — BM25 (FTS5) + dense vectors (sqlite-vec) merged via Reciprocal Rank Fusion. Exact terms via keyword, meaning via semantic, both at once.
📦 Semantic chunking — heading-aware Markdown, AST-based Python, tree-sitter JS/TS, structure-aware JSON/YAML/TOML
♻️ Incremental indexing — chunk-level SHA-256 diff means only changed chunks get re-embedded
🏷️ Namespaces — scope memories into groups (work / personal / project) with optional auto-derivation from folder names; label them (colour, description) from Settings → Namespaces in the Web UI
🧹 Maintenance — near-duplicate detection with merge, time-based score decay, TTL expiration, auto-tagging
🔄 Export / import — JSON bundle backup and restore with re-embedding
🌐 Web UI — polished SPA dashboard for search, sources, indexing, tags, and timeline (mm web --dev unlocks the full maintainer surface including Sessions, Working Memory, and Health Report)
🧭 Context Gateway — keep canonical Skills, Commands, and Subagents in a project or user Store, optionally install reusable Wiki assets, then push them to supported runtimes
⚙️ Scriptable CLI — --json output on mm status and write commands (mm add / mm reset / mm purge); mm warmup pre-loads local models so the first query skips cold-start
🛠️ 9-tool core mode — a compact default surface, with mem_do routing the full feature set without loading every tool into agent context
📌 Pinned Context — small file-backed user/project/agent blocks are composed before retrieved memory
🕸️ LangGraph Store — optional MemtomemBaseStore supplies tuple-namespace JSON persistence and search
Hybrid Store — MemtomemHybridStore adds explicit-path SQLite persistence, BM25/dense/RRF retrieval, TTL, and diagnostics; see the guide

The full surface contains 100 tools. It includes the Pinned Context actions (mem_pinned_list/get/set/delete, mem_context_compose) and review-first formation actions (mem_formation_scan, mem_candidate_propose/list/evidence/review/recover). See the complete MCP table for every category.

Documentation

Full documentation lives in the memtomem GitHub repo:

Guide	Topic
Getting Started	Start here — install, configure, save and find your first memory
한국어 바이브코딩 빠른 시작	Claude Code·Codex CLI에서 10~15분 안에 기억 저장·검색
MCP Client Setup	Connect Claude Code, Cursor, Codex, and other clients
Core memory tools	Index existing notes, search, and manage memories
Configuration	Supported config files, precedence, and environment variables
Embeddings	ONNX, Ollama, and OpenAI providers, model dimensions, switching models
Context Gateway	Author and push canonical Skills, Commands, and Subagents to each type's supported AI tools
Operations & troubleshooting	Web UI, privacy audits, diagnostics, and recovery
Reference	Complete feature reference — all tools and patterns
memtomem-stm	Optional STM proxy for proactive memory surfacing (separate package)