memtomem 0.1.11

Markdown-first memory infrastructure for AI agents with hybrid search

memtomem

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

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. Install memtomem (requires Python 3.12+)
uv tool install memtomem        # or: pipx install memtomem

# 2. Run the 9-step setup wizard
#    (picks embedding provider, optional reranker, memory folder, MCP editor)
mm init    # on PATH after `uv tool install` — no `uv run` needed

The wizard's default is keyword-only (BM25, no external deps). Pick ONNX (local, no server), Ollama (local server), or OpenAI (cloud) for semantic search — see Embeddings.

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. ~/.memtomem/memories is always indexed, and well-known AI tool directories (~/.claude/projects, ~/.gemini, ~/.codex/memories) are auto-discovered when they exist. Set MEMTOMEM_INDEXING__MEMORY_DIRS to add custom paths.

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

Or add the following to your MCP client config file — the path depends on the editor: ~/.cursor/mcp.json (Cursor), ~/.codeium/windsurf/mcp_config.json (Windsurf), ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop), or ~/.gemini/settings.json (Gemini CLI):

{
  "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
• 🛠️ 74 MCP tools — full feature surface as MCP tools, with mem_do meta-tool routing all registered 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
Reference	Complete feature reference — all tools and patterns
Configuration	All MEMTOMEM_* environment variables
Embeddings	ONNX, Ollama, and OpenAI providers, model dimensions, switching models
MCP Client Setup	Editor-specific configuration
memtomem-stm	Optional STM proxy for proactive memory surfacing (separate package)

License

Apache License 2.0 — see LICENSE for details.