mnemon-memory 0.6.0rc1

Universal long-term memory layer for AI agents via MCP

mnemon

One memory vault. Every MCP client. Self-hosted.

Status: alpha — interfaces may change. Issues and PRs welcome.

Claude Code, Cursor, claude.ai web/mobile/desktop, Claude Desktop, Gemini CLI — one vault shared across all of them.

mnemon is a Model Context Protocol server with hybrid BM25 + vector search. Your data stays on your machine or your own Fly app.

Platforms: Tested on macOS 14+. Linux should work. Windows untested.

Two product lanes: local and web

Capability	mnemon local	mnemon web
Claude Code (CLI)	✅	✅
Claude Desktop (Mac/Win app)	✅	✅
Cursor	✅	✅
Gemini CLI	✅	✅
Any local MCP client	✅	✅
claude.ai (web)	❌	✅
Claude mobile app	❌	✅
Memory shared across laptop + desktop	❌	✅
Durable off-machine backup	❌ (manual file copy)	✅ (S3)
External accounts required	none	Fly.io + AWS
Credit card required	no	yes (both free tiers)
First-install setup time	~2 min	~15 min
Ongoing cost	$0	~$0 on free tiers
Cold-start latency after idle	none	2–5s

• mnemon local — one machine, one or more MCP clients. Zero external accounts. pip install mnemon-memory && mnemon setup.
• mnemon web — memory across devices + claude.ai + mobile. Requires Fly.io + AWS. mnemon upgrade web --app-name my-mnemon.

Start local, upgrade later — your vault rides along. mnemon downgrade local reverts. Comfortable up to ~50k memories.

Install

pip install mnemon-memory

Optional: pip install "mnemon-memory[ui]" for the Streamlit dashboard, or [llm] for the on-device 1.7B model.

From source (e.g. to try unreleased fixes on main):

git clone https://github.com/cipher813/mnemon.git
cd mnemon
pip install -e .

For contributors (adds pytest, ruff, and other test/lint tooling):

pip install -e ".[dev]"

Quick Start

Local

pip install mnemon-memory
mnemon setup

Auto-detects Claude Code, Claude Desktop, Cursor, Gemini CLI — configures each, then runs mnemon doctor.

First memory_search takes ~10–20s (one-time FastEmbed model download). Subsequent calls are fast.

Web

Prereqs: flyctl authenticated, aws CLI configured, an S3 bucket.

export MNEMON_S3_BUCKET=my-mnemon-vault
mnemon upgrade web --app-name my-mnemon

After it finishes, add https://my-mnemon.fly.dev/mcp to claude.ai and the Claude mobile app manually (Settings → Connectors / Connected Apps).

Downgrade back to local

mnemon downgrade local --destroy-fly-app

Pulls the Fly vault back via S3, reconfigures clients to stdio, optionally destroys the Fly app. No memories lost.

Visualize your vault

pip install "mnemon-memory[ui]"
mnemon dashboard

Streamlit UI at http://localhost:8503 — stats, search, timeline, UMAP graph view, profile. Works against local and remote vaults.

Use it

Once configured, mnemon works automatically — memories save and surface during your sessions. You can also interact directly:

mnemon search "deployment architecture"
mnemon save "DB migration plan" "Migrate from PostgreSQL to DynamoDB in Q3"
mnemon forget 42
mnemon status

MCP Tools

Retrieval

Tool	Description
memory_search	Hybrid BM25 + vector search with composite scoring (relevance + recency + confidence)
memory_get	Fetch a specific memory by ID with full content
memory_timeline	Recent memories in reverse chronological order
memory_related	Find memories related to a given memory via the relationship graph

Mutation

Tool	Description
memory_save	Store a new memory with content type classification and auto-embedding
memory_pin	Pin a memory to boost confidence and prevent archival
memory_forget	Soft-delete a memory (marked as invalidated, not physically removed)

Lifecycle

Tool	Description
memory_status	Vault health stats — counts by type, vectors, pinned/invalidated
memory_sweep	Archive stale memories past their half-life (dry-run by default)
memory_rebuild	Re-embed all documents (use after upgrading embedding model)

Intelligence

Tool	Description
memory_check_contradictions	Check a memory for conflicts using vector similarity + LLM classification
profile_get	Synthesized user profile from stored preferences and decisions
profile_update	Manually add a fact to the user profile

Memory Types

Each memory has a content type that determines its default confidence and decay half-life:

Type	Default Confidence	Half-Life	Use for
decision	0.85	Never	Architectural choices, design decisions
preference	0.80	Never	User workflow habits, style preferences
antipattern	0.80	Never	Things that failed, approaches to avoid
observation	0.70	90 days	Learned facts, discovered behaviors
research	0.70	90 days	Investigation results, findings
project	0.65	120 days	Project status, goals, context
handoff	0.60	30 days	Session summaries for continuity
note	0.50	60 days	General notes, default type

Memories with access activity decay slower — each access extends the effective half-life by 10%, up to 3x the base value.

Claude Code Hooks

When configured via mnemon setup, three hooks are installed on Claude Code:

Hook	Event	Timeout	Description
Context surfacing	UserPromptSubmit	8s	Searches vault and injects relevant memories as context
Session extractor	Stop	30s	Extracts decisions, preferences, and observations from the transcript
Handoff generator	Stop	30s	Creates a session summary for the next session

The extractor and handoff generator use LLM-based extraction when mnemon[llm] is installed, with regex/heuristic fallback otherwise.

Uninstall

Remove mnemon state from this machine. Nothing user-owned in the cloud is touched.

mnemon uninstall [--yes] [--keep-vault]

What mnemon uninstall removes

• ~/.mnemon/ — vault (SQLite + vectors), archive/, remote_url, local_token, models cache. With --keep-vault, this directory is preserved.
• Claude Code MCP registration (claude mcp remove --scope user mnemon).
• mnemon hook + mcpServers entries in ~/.claude/settings.json.
• mnemon entry in ~/.cursor/mcp.json.
• mnemon entry in Claude Desktop's config.

What mnemon uninstall does NOT touch

• The mnemon-memory Python package. Use pip uninstall mnemon-memory separately.
• Your Fly.io app. Destroy it first with mnemon downgrade local --destroy-fly-app if you want the app gone — that pulls the remote vault back to local so no memories are lost.
• Your S3 bucket contents. mnemon has no sync delete.
• claude.ai + Claude mobile MCP entries. These live in your Anthropic account. claude mcp list shows them with a claude.ai prefix. Remove via Settings → Connectors in the claude.ai web UI. If mnemon uninstall detects one, it surfaces a ⚠ REQUIRED bullet pointing you there.

Memory retention matrix

Command	Local ~/.mnemon/default.sqlite	Fly volume	S3 bucket contents
mnemon uninstall	deleted (unless --keep-vault)	untouched	untouched
mnemon uninstall --keep-vault	untouched	untouched	untouched
mnemon downgrade local	replaced with Fly state (via S3 pull)	untouched (keeps running)	untouched
mnemon downgrade local --destroy-fly-app	replaced with Fly state	destroyed (after data was pulled to local)	untouched
mnemon upgrade web	archived to archive/pre-web-<date>.sqlite	newly created, seeded from S3	written to (push)
mnemon sync push / mnemon sync pull	read/write local	—	read/write

Memories are always recoverable as long as at least one of {S3 backup, Fly volume, local vault, local archive} exists.

Common flows

Test from scratch on one machine:

mnemon uninstall --yes
pip install -e .           # or: pip install mnemon-memory
mnemon setup

Stop using mnemon entirely:

mnemon downgrade local --destroy-fly-app    # tears down Fly, preserves vault via S3 pull
mnemon uninstall --yes                      # removes local state
pip uninstall mnemon-memory                 # removes the package
# Then remove mnemon entries in claude.ai and the Claude mobile app manually.
# Delete your S3 bucket contents if you want no residual memory data.

Move to a new machine (preserve all memories):

# Old machine:
mnemon sync push
mnemon uninstall --yes

# New machine:
pip install mnemon-memory
mnemon setup claude-code --remote-url https://<your-app>.fly.dev/mcp

Development

pip install -e ".[dev]"
pytest

License

MIT