memtomem

# memtomem

> Markdown-first long-term memory for AI coding agents — your files stay yours, and core usage is hook-free by default.

[![PyPI](https://img.shields.io/pypi/v/memtomem)](https://pypi.org/project/memtomem/)
[![Downloads](https://img.shields.io/pypi/dm/memtomem)](https://pypi.org/project/memtomem/)
[![GitHub stars](https://img.shields.io/github/stars/memtomem/memtomem)](https://github.com/memtomem/memtomem/stargazers)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-green)](https://python.org)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![CLA](https://img.shields.io/badge/CLA-required-green)](CLA.md)
[![Safety](https://img.shields.io/badge/safety-no%20vulnerabilities-brightgreen)](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](https://github.com/memtomem/memtomem/issues) · [Discussions](https://github.com/memtomem/memtomem/discussions).

<p align="center">
  <img src="docs/assets/README-hero.gif" alt="memtomem Web UI dashboard — namespaces, file types, chunk-size buckets, activity timeline" width="640">
</p>

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.

```mermaid
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. Claude Code or Codex CLI user? See the [Korean vibe-coding quickstart](docs/guides/vibe-coding-getting-started-ko.md).

---

## 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, TOML, Python, JS/TS |
| Vendor lock-in | Your `.md` files are the source of truth. The DB is a rebuildable cache |
| Hidden automation is hard to reason about | Core memory operations run only when you call them; optional client hooks are explicit, removable integrations |

---

## Quick Start

### 1. Install

```bash
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, code chunker, and the Web UI. The Ollama and OpenAI embedding providers need no extra; they work on any install. For a smaller install without those downloads (about 50 MB installed instead of about 340 MB, before any model download), 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](https://github.com/memtomem/memtomem/releases) right after installing, `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`. To upgrade an existing uv tool install, use `mm upgrade` rather than re-running `uv tool install`; see the [CLI reference](docs/guides/reference/data-config-cli.md#cli-reference) for what it preserves and stops.

> **`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

> **After upgrading the Claude plugin:** re-check `/mcp` after reloading.
> The plugin launches `memtomem[onnx]==0.6.7`. A manual registration whose launch
> differs — base-only `memtomem`, or the ONNX launch pinned to an earlier
> release — no longer matches for deduplication and may expose
> duplicate tools. Confirm the manual entry's name and scope, then align its
> launch command with the plugin or remove that redundant registration.

```bash
mm init                               # preset picker, then memory_dir + MCP
```

The interactive picker starts with three presets — **Minimal** (BM25, no downloads), **English (Recommended)** (ONNX `multilingual-e5-small` + English reranker + auto-discover providers), **Korean-optimized** (ONNX `multilingual-e5-small` + `kiwipiepy` tokenizer, no 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.

Choose **Minimal** for the fastest no-download first proof; rerun `mm init`
later when you are ready to add semantic search.

> **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:

```bash
mm init --non-interactive                   # minimal preset, no prompts
mm init --preset korean --non-interactive   # 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.

<a id="3-use"></a>
### 3. Verify a complete memory round trip

The first success path does not require an existing notes directory or a connected editor:

```bash
mm status
mm add "Deployment checklist uses blue-green rollout" --tags ops
mm search "blue-green"
```

`mm add` writes to your configured user memory directory and indexes the entry immediately. The final command should return the sentence you just added.

Then verify the editor connection:

```text
"Call the mem_status tool"
```

To bring existing notes into the same index, point `mm index` at a directory that already exists:

```bash
mm index /path/to/your/notes
```

`mm status --json` (or `--format json`) provides the same status as machine-readable output for scripts and CI.

<a id="4-web-ui-optional"></a>
### 4. Open the Web UI (optional)

```bash
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 Sessions, Working Memory, and Health Report.

<details>
<summary><b>Other install options</b></summary>

<a id="minimal-install"></a>
**Minimal** (no bundled model, about 50 MB):
```bash
uv tool install memtomem             # no extras — no local ONNX model, Web UI or Korean tokenizer until you add them; Ollama/OpenAI embeddings still work
```
Opt in later per-feature: `uv tool install --reinstall 'memtomem[onnx,web]'` (see the [extras table](docs/guides/getting-started.md#optional-extras)). List every extra you want to keep, because `--reinstall` replaces the whole set. A plain `mm upgrade` keeps the extras it detects from the current install, but an explicit `mm upgrade --extras` list must name the complete set too.

**Project-scoped** (per-project isolation):
```bash
uv add 'memtomem[all]' && uv run mm init    # all commands need `uv run` prefix
```

**No install** (uvx on demand):
```bash
claude mcp add memtomem -s user -- uvx --isolated --from "memtomem[all]==0.6.7" memtomem-server
```

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

</details>

---

## 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)
- **Context Gateway** — keep canonical Skills, Commands, and Subagents in a project or user Store, optionally install reusable assets from a separate Wiki, then push them to supported AI runtimes. See [Context Gateway](docs/guides/context-gateway.md).
- **MCP tools** — `mem_do` meta-tool routes all non-core actions in `core` mode for minimal context usage
- **Predictable core** — memory operations run on explicit CLI/MCP calls (`mm add`, `mem_add`, `mem_index`, etc.). Optional client hooks are installed and removed separately rather than being a hidden runtime default.
- **Scriptable CLI** — JSON output for scripts: `--json` on `mm status`, the write commands (`mm add` / `mm reset` / `mm purge`), `mm session start` / `end` / `list` / `events`, `mm schedule list`, `mm watchdog status` / `run` and `mm doctor`, and `--format json` on `mm search` and `mm recall`; `mm warmup` pre-loads local models so the first query skips the cold-