Metadata-Version: 2.4
Name: mnemon-memory
Version: 0.6.0rc2
Summary: Universal long-term memory layer for AI agents via MCP
Project-URL: Homepage, https://github.com/cipher813/mnemon
Project-URL: Repository, https://github.com/cipher813/mnemon
Project-URL: Issues, https://github.com/cipher813/mnemon/issues
Project-URL: Changelog, https://github.com/cipher813/mnemon/blob/main/CHANGELOG.md
Author-email: Brian McMahon <cipher813@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,llm,mcp,memory,sqlite,vector-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: fastembed>=0.3
Requires-Dist: httpx[socks]>=0.25
Requires-Dist: mcp>=1.27
Requires-Dist: numpy>=1.24
Provides-Extra: all
Requires-Dist: authlib>=1.3; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: huggingface-hub>=0.20; extra == 'all'
Requires-Dist: llama-cpp-python>=0.3; extra == 'all'
Requires-Dist: plotly>=5.18; extra == 'all'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
Requires-Dist: pytest-cov>=5.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: starlette>=0.37; extra == 'all'
Requires-Dist: streamlit>=1.30; extra == 'all'
Requires-Dist: umap-learn>=0.5; extra == 'all'
Requires-Dist: uvicorn>=0.29; extra == 'all'
Provides-Extra: dev
Requires-Dist: authlib>=1.3; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: starlette>=0.37; extra == 'dev'
Requires-Dist: uvicorn>=0.29; extra == 'dev'
Provides-Extra: llm
Requires-Dist: huggingface-hub>=0.20; extra == 'llm'
Requires-Dist: llama-cpp-python>=0.3; extra == 'llm'
Provides-Extra: server
Requires-Dist: authlib>=1.3; extra == 'server'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'server'
Requires-Dist: starlette>=0.37; extra == 'server'
Requires-Dist: uvicorn>=0.29; extra == 'server'
Provides-Extra: ui
Requires-Dist: plotly>=5.18; extra == 'ui'
Requires-Dist: streamlit>=1.30; extra == 'ui'
Requires-Dist: umap-learn>=0.5; extra == 'ui'
Description-Content-Type: text/markdown

# mnemon

[![Status](https://img.shields.io/badge/status-alpha-orange.svg)]()
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet.svg)](https://modelcontextprotocol.io)
[![PyPI](https://img.shields.io/badge/PyPI-v0.6.0rc1-blue.svg)](https://pypi.org/project/mnemon-memory/)

> One memory vault. Every MCP client. Self-hosted.
>
> **Status:** alpha — interfaces may change. [Issues](https://github.com/cipher813/mnemon/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](https://modelcontextprotocol.io) 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

```bash
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`):

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

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

```bash
pip install -e ".[dev]"
```

## Quick Start

### Local

```bash
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.

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

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

```bash
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:

```bash
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.

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

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

**Stop using mnemon entirely:**

```bash
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):**

```bash
# 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
```

## Install troubleshooting

### Intel Mac + Python 3.12: `pip install "mnemon-memory[ui]"` fails building `llvmlite` / `numba`

The `[ui]` extra pulls in `umap-learn`, which requires `numba` + `llvmlite`. Starting with `numba 0.63`, those packages only ship macOS wheels for Apple Silicon (arm64). On an Intel Mac (x86_64), pip falls back to a source build and fails with `llvmlite needs CMake tools to build`.

Pin to the last versions that ship x86_64 macOS wheels:

```bash
pip install 'numba==0.62.1' 'llvmlite==0.45.1' 'mnemon-memory[ui]'
```

If pip then complains about NumPy, add `'numpy<2.3'` to the same command.

Apple Silicon, Linux, and Windows are unaffected — prebuilt wheels exist on those platforms.

## Development

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT
