memtomem 0.1.2

Markdown-first memory infrastructure for AI agents with hybrid search

memtomem

Markdown-first long-term memory infrastructure for AI agents. Hybrid keyword + semantic search across your notes, docs, and code via the Model Context Protocol.

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) 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 bge-m3 embeddings

Quick Start

# 1. Prerequisites — Python 3.12+ and Ollama (ollama.com)
ollama pull nomic-embed-text    # ~270MB, one-time

# 2. Install memtomem
uv tool install memtomem        # or: pipx install memtomem

# 3. Run the 7-step setup wizard (picks embedding, memory folder, editor)
mm init    # on PATH after `uv tool install` — no `uv run` needed

Then in your AI editor, ask:

"Call the mem_status tool"   →  confirms the server is connected
"Index my notes folder"      →  mem_index(path="~/notes")
"Search for deployment"      →  mem_search(query="deployment checklist")
"Remember this insight"      →  mem_add(content="...", tags="ops")

That's it. Your agent now has a long-term memory built from plain markdown files.

For full setup, OpenAI configuration, and troubleshooting, see the Getting Started guide.

Prefer no install? (uvx direct, MCP only)

If you'd rather skip the CLI install, uvx will download and run memtomem on demand. You'll need to set MEMORY_DIRS yourself — without it mem_index has nothing to index.

claude mcp add memtomem -s user -- uvx --from memtomem memtomem-server

Or add to .mcp.json for Cursor / Windsurf / Claude Desktop:

{
  "mcpServers": {
    "memtomem": {
      "command": "uvx",
      "args": ["--from", "memtomem", "memtomem-server"],
      "env": {
        "MEMTOMEM_INDEXING__MEMORY_DIRS": "[\"/path/to/your/notes\"]"
      }
    }
  }
}

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
• 🧹 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 — full-featured SPA dashboard for search, sources, indexing, tags, sessions, health monitoring
• 🛠️ 72 MCP tools — full feature surface as MCP tools, with mem_do meta-tool routing 64 actions in core mode (default) for minimal context usage

Documentation

Full documentation lives in the memtomem GitHub repo:

Guide	Topic
Getting Started	Start here — install, setup wizard, first use
Hands-On Tutorial	Follow-along with example files
User Guide	Complete feature walkthrough — all tools and patterns
Configuration	All MEMTOMEM_* environment variables
Embeddings	Ollama and OpenAI providers, model dimensions, switching models
MCP Client Setup	Editor-specific configuration
Agent Memory Guide	Sessions, working memory, procedures, multi-agent
Web UI Guide	Visual dashboard reference
Hooks	Claude Code hooks for automatic indexing and search
memtomem-stm	Optional STM proxy for proactive memory surfacing (separate package)

License

Apache License 2.0 — see LICENSE for details.