A lightweight, inspectable, local-first memory engine for AI coding agents — with built-in version history and time-travel.
%%{init: {
"theme": "base",
"themeVariables": {
"background": "#ffffff",
"primaryTextColor": "#24292f",
"primaryColor": "#f6f8fa",
"primaryBorderColor": "#0969da",
"lineColor": "#57606a",
"secondaryColor": "#ddf4ff",
"tertiaryColor": "#d8f5d0"
}
}}%%
mindmap
root((🧠 Mnemix))
📝 Remember
observations
decisions
preferences
facts & procedures
🔍 Recall
pinned context first
summaries on demand
full archival depth
🔎 Search
full-text across scopes
filter by kind & tags
ranked by importance
🛡️ Protect
named checkpoints
versioned history
time-travel restore
🔬 Inspect
human-readable CLI
store stats & diffs
import / export
AI coding agents have no continuous memory. Every session starts cold. Mnemix changes that — giving your agent a structured, local memory store that persists between sessions, supports rich retrieval, and lets you inspect, restore, and version everything.
No cloud, no daemon, no configuration sprawl. Just a local store on your filesystem that your agent can write to and read from, with a clean CLI and Python client sitting on top.
Website: mnemix.org
Docs: docs.mnemix.org
An agent calls remember to persist an observation, decision, or fact. Later sessions call recall or search to retrieve the most relevant context. The full version history of the store is preserved — you can checkpoint before risky operations, list what changed, and restore to any prior state.
sequenceDiagram
participant A as 🤖 AI Agent
participant TP as Mnemix
participant S as 💾 Local Store
rect rgb(15, 118, 110)
Note over A,S: Session 1
A->>TP: remember(scope, kind, title, summary, detail)
TP->>S: persist memory → Version N created
end
rect rgb(3, 105, 161)
Note over A,S: Session 2
A->>TP: recall(scope="my-project")
TP->>S: query versions + index
S-->>TP: matching memories
TP-->>A: pinned_context · summaries · archival
end
Context is returned in three layers based on relevance:
| Layer | What it contains | When it loads |
|---|---|---|
pinned_context |
Explicitly pinned, always-relevant memories | Always first |
summaries |
High-importance and recent distilled memories | By default |
archival |
Full historical record | On request |
This progressive disclosure pattern means you never flood an agent's context window with noise.
- Scoped memory — organize memories by project or context
- Typed memory kinds —
observation,decision,preference,summary,fact,procedure,warning - Full-text search — fast FTS with scope and importance filters
- Pinned context — pin critical decisions or preferences to always surface first
- Version history — every write creates an immutable version; inspect and browse the full timeline
- Checkpoints — named, human-readable stable points in the version history
- Time-travel restore — restore the store to any prior version or checkpoint as a new head state
- Import / export — portable store archives
- Optional vector retrieval foundation — persisted embedding settings, coverage inspection, and backend support for semantic and hybrid retrieval
- Store optimization — compact and prune old data with safety checkpoints built in
- Human-readable CLI — inspect the full store state from the terminal
- Python client — typed, thin wrapper for use in Python agents and scripts
- Local-first, no cloud — runs entirely on your filesystem, zero external dependencies
On supported platforms, the PyPI wheel bundles the mnemix CLI binary:
pip install mnemixIf you want the CLI as a standalone tool, prefer pipx:
pipx install mnemixIf no bundled wheel is available for your platform, install the CLI from source:
cargo install --path crates/mnemix-climnemix --store .mnemix initmnemix --store .mnemix remember \
--id mem-001 \
--scope my-project \
--kind observation \
--title "Decided to use LanceDB for local storage" \
--summary "LanceDB chosen for Arrow-native embedded storage with FTS and versioning." \
--detail "Evaluated SQLite, DuckDB, and LanceDB. LanceDB wins on versioning and vector support." \
--importance 80 \
--tag architecture --tag storagemnemix --store .mnemix recall --scope my-projectmnemix --store .mnemix search --text "storage decision" --scope my-projectmnemix --store .mnemix vectors showmnemix --store .mnemix uiThe TUI now exposes recent, pinned, and search views along with compact vector-readiness status and retrieval-mode availability inside the same interface.
mnemix --store .mnemix checkpoint \
--name before-refactor \
--description "Stable state before large codebase restructure"mnemix --store .mnemix restore --checkpoint before-refactorMnemix works out of the box with lexical search and layered recall. Vector support is optional and store-scoped: you can persist embedding settings, inspect coverage, and prepare a store for semantic or hybrid retrieval without changing the default workflow.
# Create a machine-local provider profile
mnemix providers set-cloud \
--name openai \
--model text-embedding-3-small \
--base-url https://api.openai.com/v1 \
--api-key-env OPENAI_API_KEY
# Or point at a local OpenAI-compatible embedding runtime
mnemix providers set-local \
--name ollama \
--model nomic-embed-text \
--endpoint http://127.0.0.1:11434/v1
# Validate the provider and check whether it matches the current store
mnemix --store .mnemix providers validate --name openai
# Persist store-level vector settings directly from the provider
mnemix --store .mnemix vectors enable \
--provider openai \
--auto-embed-on-write
# Inspect current vector status and coverage
mnemix --store .mnemix vectors show --provider openai
# Backfill persisted embeddings
mnemix --store .mnemix vectors backfill --apply --provider openai
# Run semantic and hybrid retrieval explicitly
mnemix --store .mnemix search --text "storage decision" --scope my-project --mode semantic --provider openai
mnemix --store .mnemix recall --text "architecture" --scope my-project --mode hybrid --provider openaiProvider profiles are machine-local runtime state. Store-level vector settings still live inside .mnemix, which keeps exports portable and inspectable while keeping secrets out of the store itself.
The current CLI now supports:
- named provider profiles for cloud and local OpenAI-compatible embedding runtimes
- provider validation with resolved model and dimension reporting
- provider-derived
vectors enable vectors backfill --apply --provider <NAME>- semantic-only and hybrid top-level
searchandrecall - explicit provider/store mismatch reporting before embedding work starts
Lexical retrieval remains the default baseline. Semantic and hybrid execution are always explicit and require a compatible provider profile at runtime.
Vector state is preserved during export and staged import, so portable archives and import-review flows do not silently drop persisted embeddings or vector configuration.
For library use, install from PyPI:
pip install mnemixFor CLI-first use, install with pipx:
pipx install mnemixOn supported platforms, the wheel includes the
mnemixCLI binary and works without any extra setup. If you are on an unsupported platform or using a source install, install the CLI separately and ensure it is onPATH, or setMNEMIX_BINARY=/path/to/mnemix.
from pathlib import Path
from mnemix import Mnemix, RememberRequest
client = Mnemix(store=Path(".mnemix"))
client.init()
client.remember(RememberRequest(
id="mem-001",
scope="my-project",
kind="decision",
title="Use LanceDB for local storage",
summary="LanceDB chosen for Arrow-native embedded storage with FTS and versioning.",
detail="Evaluated SQLite, DuckDB, and LanceDB. LanceDB wins on versioning and vector support.",
importance=80,
tags=["architecture", "storage"],
))
# Retrieve layered context
context = client.recall()
for entry in context.pinned_context:
print(f"[pinned] {entry.memory.title}")
# Full-text search
results = client.search("storage decision", scope="my-project")
for m in results:
print(f"{m.id}: {m.title} (importance={m.importance})")
# Inspect store stats
stats = client.stats()
print(f"Total memories: {stats.total_memories}")Mnemix keeps the base Python client generic and puts workflow policy in
host-specific adapters under adapters/.
Available adapters:
CodingAgentAdapterfor implementation tasks, decisions, procedures, and pitfallsChatAssistantAdapterfor user preferences and durable chat contextCiBotAdapterfor automated runs, checkpoints, failures, and fixesReviewToolAdapterfor review rules, conventions, and recurring issues
See:
For a more comprehensive coding-agent adapter and reusable agent memory policy
template, see the mnemix-context templates here:
mnemix-context/templates/universal/mnemix
Each memory record has:
| Field | Purpose |
|---|---|
id |
Stable identifier for this memory |
scope |
Project or context namespace |
kind |
One of observation, decision, preference, summary, fact, procedure, warning |
title |
Short human-readable label |
summary |
Distilled, compact version of the memory |
detail |
Full detail — the complete context |
importance |
0–100 score, controls recall ranking |
confidence |
0–100 score, how certain this memory is |
tags |
Free-form labels for filtering and search |
entities |
Named entities mentioned in this memory |
pin_reason |
If set, this memory is pinned and surfaces first in recall |
Every write creates a new immutable version:
# List versions
mnemix --store .mnemix versions
# Create a named checkpoint
mnemix --store .mnemix checkpoint --name stable-baseline
# Restore the store to a named checkpoint
mnemix --store .mnemix restore --checkpoint stable-baselineRestore creates a new head state from the prior version — it does not discard history.
mnemix/
├── crates/
│ ├── mnemix-core/ # Mnemix core crate source path
│ ├── mnemix-lancedb/ # Mnemix LanceDB backend source path
│ ├── mnemix-cli/ # Mnemix CLI source path
│ ├── mnemix-types/ # Shared value objects and contracts
│ └── mnemix-test-support/
├── python/ # Python package (mnemix on PyPI)
│ ├── mnemix/
├── adapters/
│ ├── _adapter_base.py # Shared adapter utilities
│ ├── coding_agent_adapter.py # Coding-agent workflow adapter
│ ├── chat_assistant_adapter.py # Chat-assistant workflow adapter
│ ├── ci_bot_adapter.py # CI-bot workflow adapter
│ ├── review_tool_adapter.py # Review-tool workflow adapter
│ └── tests/ # Adapter smoke tests
├── examples/ # Runnable usage examples
└── docs/ # Architecture and design documentation
| Crate | Responsibility |
|---|---|
mnemix-core |
Domain types, traits, typed errors — no storage-specific code |
mnemix-lancedb |
All LanceDB and Lance storage details, behind core traits |
mnemix-cli |
CLI parsing, command dispatch, human + JSON output rendering |
mnemix-types |
Shared value objects and request/response contracts |
mnemix-test-support |
Deterministic test fixtures — non-production only |
The core crate is intentionally storage-agnostic. LanceDB details never leak into it.
The Python package is a thin subprocess wrapper over the CLI's --json output surface. No product logic is duplicated in Python — Rust is the single source of truth.
flowchart TD
A(["🐍 Python Agent"])
B["mnemix CLI<br/>--json output surface"]
C["mnemix-lancedb<br/>Rust storage backend"]
D[("Lance dataset<br/>on filesystem")]
A -- "subprocess + --json" --> B
B -- "Rust traits" --> C
C --> D
style A fill:#4f46e5,color:#fff,stroke:#4338ca
style B fill:#0f766e,color:#fff,stroke:#0d9488
style C fill:#0369a1,color:#fff,stroke:#0284c7
style D fill:#1e293b,color:#e2e8f0,stroke:#334155
Direct FFI via PyO3 is planned for a future milestone once the stable Rust API surface is locked.
| Milestone | Description | Status |
|---|---|---|
| 0 | Workspace and engineering baseline | ✅ Done |
| 1 | Core domain contract freeze | ✅ Done |
| 2 | Local LanceDB backend MVP | ✅ Done |
| 3 | Human-first CLI MVP | ✅ Done |
| 4 | Progressive disclosure and pinning semantics | ✅ Done |
| 5 | Version-aware safety features | ✅ Done |
| 6 | Python binding and first adapter | ✅ Done |
| 7 | Advanced storage workflows (branch-aware internals) | ✅ Done |
| 8 | First PyPI release | ✅ Done |
Mnemix is also part of a broader tooling ecosystem. For config-driven, multi-platform generation of AI coding resources, see mnemix-context, a companion project for generating reusable agent instructions, prompts, skills, and other coding-assistant resources.
The workspace is configured with:
- stable Rust toolchain pinning via
rust-toolchain.toml rustfmtandclippywith strict lint defaultscargo-denyfor dependency policycargo test --workspaceandcargo doc --workspaceas CI gates
./scripts/check.sh./scripts/check-python-package.shMIT — see LICENSE.