Memtomem

memtomem

> Markdown-first long-term memory for AI coding agents — your data, your quota, no hooks.

[](https://pypi.org/project/memtomem/) [](https://pypi.org/project/memtomem/) [](https://github.com/memtomem/memtomem/stargazers) [](https://python.org) [](LICENSE) [](CLA.md) [](https://data.safetycli.com/packages/pypi/memtomem)

> 🚧 Alpha — APIs, defaults, and on-disk config surfaces may still change between 0.x releases. Feedback and issue reports are especially welcome: Issues · Discussions.

memtomem turns your markdown notes, documents, and code into a searchable knowledge base that any AI coding agent can use. Write notes as plain .md files — memtomem indexes them and makes them searchable by both keywords and meaning.

flowchart LR
    A["Your files\n.md .json .py"] -->|Index| B["memtomem"]
    B -->|Search| C["AI agent\n(Claude Code, Cursor, etc.)"]

> First time here? Follow the [Getting Started](docs/guides/getting-started.md) guide — you'll have a working setup in under 5 minutes.

---

Why memtomem?

| Problem | How memtomem solves it | |---------|------------------------| | AI forgets everything between sessions | Index your notes once, search them in every session | | Keyword search misses related content | Hybrid search: exact keywords + meaning-based similarity | | Notes scattered across tools | One searchable index for markdown, JSON, YAML, Python, JS/TS | | Vendor lock-in | Your .md files are the source of truth. The DB is a rebuildable cache | | Hook-based capture chains can recurse | Captures fire only on explicit MCP tool calls — no auto-fire on every prompt or session-end |

---

Quick Start

1. Install

uv tool install 'memtomem[all]'       # or: pipx install 'memtomem[all]'
mm --version                          # verify install

[all] bundles the features the sections below describe — ONNX dense embeddings, Korean tokenizer, Ollama / OpenAI providers, code chunker, and the Web UI. For a BM25-only install without those downloads (~40 MB vs ~250 MB), see the [minimal install option](docs/guides/getting-started.md#option-a-from-pypi-recommended-for-most-users) in the Getting Started guide.

> If mm --version shows an older version than the latest release, uv is likely serving cached PyPI metadata — re-run with uv tool install 'memtomem[all]' --refresh, or clear the cache first: uv cache clean memtomem.

> mm: command not found? uv tool install drops the shim into ~/.local/bin, which isn't on $PATH in fresh shells on macOS/Linux. Run uv tool update-shell, then open a new shell and re-run mm --version.

2. Setup

mm init                               # preset picker, then memory_dir + MCP

The interactive picker starts with three presets — Minimal (BM25, no downloads), English (Recommended) (ONNX bge-small-en-v1.5 + English reranker + auto-discover providers), Korean-optimized (ONNX bge-m3 + kiwipiepy tokenizer + multilingual reranker) — plus an Advanced entry that opens the full 10-step wizard. Preset paths only ask about the memory directory and MCP registration; everything else is set from the preset.

> Indexing vs. discovery (Claude Code): provider memory folders that setup auto-discovers (e.g. ~/.claude/projects/*/memory/) are added to the search index. That is separate from the Web UI's opt-in Context Gateway scan of ~/.claude/projects/, which discovers project roots for Skills, Custom Commands, and Subagents — see [Configuration → Context Gateway](docs/guides/configuration.md#context-gateway) for the distinction and the lossy-slug caveats.

For automation / CI:

mm init -y                            # minimal preset, same as before
mm init --preset korean -y            # Korean-optimized bundle, no prompts
mm init --advanced                    # force the full 10-step wizard

See [Embeddings](docs/guides/embeddings.md) for the full model/provider matrix.

3. Use

"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"])

> Prefer the terminal? mm status is a CLI mirror of mem_status — same output, no editor needed.

4. Web UI (optional)

mm web                # polished dashboard on http://127.0.0.1:8080
mm web -b             # run in the background; logs go to ~/.memtomem/logs/web.log
mm web status         # show pid/port/start time
mm web stop           # stop the tracked Web UI process
mm web --dev          # maintainer surface (adds opt-in pages)

mm web shows the polished page set by default. Pass --dev (or set MEMTOMEM_WEB__MODE=dev in your shell profile) to expose maintainer pages like Namespaces, Sessions, Working Memory, and Health Report.

Other install options

Minimal (BM25-only, ~40 MB):

uv tool install memtomem             # no extras — dense search, web UI, Korean tokenizer unavailable until you add them

Opt in later per-feature: uv tool install --reinstall 'memtomem[onnx,web]' (see the extras table in [Getting Started](docs/guides/getting-started.md#option-c-from-source-for-development-or-testing)).

Project-scoped (per-project isolation):

uv add 'memtomem[all]' && uv run mm init    # all commands need `uv run` prefix

No install (uvx on demand):

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

See [MCP Client Setup](docs/guides/mcp-clients.md) for Cursor / Windsurf / Claude Desktop / Gemini CLI / Kimi CLI.

---

Key Features

• Hybrid search — BM25 keyword + dense vector + RRF fusion in one query
• Semantic chunking — heading-aware Markdown, AST-based Python, tree-sitter JS/TS, structure-aware JSON/YAML/TOML
• Incremental indexing — chunk-level SHA-256 diff; only changed chunks get re-embedded
• Namespaces — organize memories into scoped groups with auto-derivation from folder names; review and label them (colour, description) from Settings → Namespaces in the Web UI
• Maintenance — near-duplicate detection, time-based decay, TTL expiration, auto-tagging
• Web UI — visual dashboard for search, sources, tags, timeline, dedup, and more (mm web --dev for the full maintainer surface)
• MCP tools — mem_do meta-tool routes all non-core actions in core mode for minimal context usage
• Predictable surface — memory operations fire only on explicit MCP tool calls (mem_add, mem_index, etc.), not from background hooks attached to every prompt or session-end. Less magic, fewer surprises.
• Scheduled jobs — mm schedule add/list/run-now/delete (or mem_do(action="schedule_*")) for cron-driven compaction, importance decay, dead-link cleanup, and dedup scans

---

Ecosystem

| Package | Description | |---------|-------------| | memtomem | Core — MCP server, CLI, Web UI, hybrid search, storage | | memtomem-stm | STM proxy — proactive memory surfacing via tool interception |

---

Documentation

Hosted at memtomem.com — also available as Markdown in this repo. New to memtomem? The guides have a [suggested reading order](docs/guides/README.md). The table below follows it:

| Guide | Description | |-------|-------------| | [Getting Started](docs/guides/getting-started.md) | Install, setup wizard, first use | | [Example notebooks](examples/notebooks/) | Runnable Python-API walkthrough (start with 01_hello_memory.ipynb, local ONNX — no server) | | [MCP Client Setup](docs/guides/mcp-clients.md) | Editor-specific configuration | | [Configuration](docs/guides/configuration.md) | All MEMTOMEM_* environment variables | | [Embeddings](docs/guides/embeddings.md) | ONNX, Ollama, and OpenAI embedding providers | | [LLM Providers](docs/guides/llm-providers.md) | Ollama, OpenAI, Anthropic, and compatible endpoints | | [Context Gateway](docs/guides/context-gateway.md) | Share Skills, Commands, and Subagents across your AI tools from one Store | | [Multi-device sync](docs/guides/multi-device-sync.md) | Sync markdown memories across personal devices via a private git repo | | [Reference](docs/guides/reference.md) | Complete feature reference for all tools and patterns | | [Uninstalling memtomem](docs/guides/uninstall.md) | Clean removal steps |

---

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and the contributor guide.

License

[Apache License 2.0](LICENSE). Contributions are accepted under the terms of the [Contributor License Agreement](CLA.md).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: memtomem
• Source: memtomem/memtomem
• License: Apache-2.0
• Homepage: https://memtomem.com

Install and usage instructions live in the source repository linked above.