Mnemex

# What Is This? (ELI5) ## The Problem You're chatting with Claude. You tell it "I prefer TypeScript over JavaScript" or "I'm working on a project called BlueSky." Then, three days later in a new conversation, Claude has completely forgotten. You have to repeat yourself over and over. **This is annoying.** ## What This Repo Does This is **Mnemex** - a **memory system for AI assistants like Claude**. It makes Claude remember things you tell it, but in a smart, human-like way: - 🧠 **Remembers important stuff** - Preferences, decisions, facts about you - ⏰ **Forgets naturally** - Old, unused memories fade away (just like human memory) - 💪 **Gets stronger with use** - The more you reference something, the longer Claude remembers it - 📦 **Saves important things permanently** - Frequently used memories get promoted to long-term storage ## A Simple Analogy Think of it like your own memory: - **Short-term memory** is like remembering what you had for breakfast this morning. If it's not important, you'll forget it in a few days. - **Long-term memory** is like remembering your best friend's name. You use it all the time, so it never fades. This system works the same way: - New memories start in **short-term storage** with a 3-day "half-life" - If you keep using them, they get **stronger and last longer** - Really important memories get **promoted to permanent storage** (your Obsidian notes) ## How It Actually Works (Simple Version) ### 1. You Talk to Claude ``` You: "I prefer dark mode in all my apps" ``` Claude automatically saves this as a memory with tags like `[preferences, ui, dark-mode]`. ### 2. Time Passes After 3 days, this memory is at "half strength." After a week, it's fading. After two weeks, it might get forgotten completely. ### 3. You Mention It Again ``` You: "Can you make this app in dark mode?" ``` Claude searches its memory, finds your preference, and **reinforces it** (makes it stronger). Now it'll last longer. ### 4. Automatic Promotion If you reference dark mode preferences 5 times in two weeks, Claude thinks "this is important!" and saves it to your **Obsidian vault** as a permanent note. Now it'll never be forgotten. ### 5. Manual Promotion You can also just tell Claude directly: ``` You: "Never forget this: I'm allergic to peanuts" You: "Make a note that I prefer 2-space indentation" ``` Claude will save these with high importance and promote them to permanent storage immediately. ## What Makes This Different? Most memory systems are dumb: - **Time-based expiration (TTL)**: "Delete after 7 days" - doesn't care if you used it 100 times - **LRU cache**: "Keep last 100 items" - dumps important stuff just because it's old This system is **smart**: - Combines **recency** (when did I last use this?), **frequency** (how often do I use this?), and **importance** (did I mark this as critical?) - Memories fade naturally over time (like human memory) - Frequently used memories stick around longer - You can manually boost important things by asking Claude to "never forget" or "make a note" ## How to Use It ### Step 1: Install ```bash # Install Mnemex as a UV tool uv tool install git+https://github.com/simplemindedbot/mnemex.git ``` This installs `mnemex` and all 7 CLI commands in one step! ### Step 2: Configure (Optional) Create `~/.config/mnemex/.env` if you want custom settings: ```bash # Where to store memories (default: ~/.config/mnemex/jsonl) MNEMEX_STORAGE_PATH=~/.config/mnemex/jsonl # How fast memories fade (3 days = default) MNEMEX_PL_HALFLIFE_DAYS=3.0 # Where to save important memories permanently (optional) LTM_VAULT_PATH=~/Documents/Obsidian/MyVault ``` **Note**: Configuration goes in `~/.config/mnemex/.env` - create it if it doesn't exist! ### Step 3: Connect to Claude Add this to your Claude Desktop config file: **Location**: `~/Library/Application Support/Claude/claude_desktop_config.json` ```json { "mcpServers": { "mnemex": { "command": "mnemex" } } } ``` That's it! Just one line - no paths, no environment variables. ### Step 4: Restart Claude Desktop Now Claude has memory. ## What Happens Now? Claude will automatically: - **Save** things you tell it (preferences, decisions, project info) - **Recall** them when relevant to the conversation - **Reinforce** memories you use frequently - **Forget** old, unused stuff - **Promote** important memories to permanent storage You don't have to think about it. It just works. You can also **manually save** things permanently: ``` You: "Make a note: I'm allergic to shellfish" You: "Never forget this: my API key rotation schedule is monthly" You: "Remember permanently: I prefer functional programming style" ``` ## Under the Hood (Slightly More Technical) ### The Scoring Formula Every memory gets a "score" that determines whether it stays or gets forgotten: ``` score = (use_count ^ 0.6) × (decay_over_time) × importance ``` - **use_count**: How many times you've referenced this - **decay_over_time**: Exponential decay (half-life = 3 days by default) - **importance**: 1.0 for normal stuff, up to 2.0 for critical things ### Thresholds - **Score < 0.05**: Memory gets deleted (forgotten) - **Score ≥ 0.65**: Memory gets promoted to permanent storage - **OR used 5+ times in 14 days**: Also gets promoted ### Example: Watch a Memory Fade Let's say you tell Claude "I'm learning Rust" but never mention it again: | Time | Score | Status | |------|-------|--------| | Right now | 1.00 | Fresh memory | | 1 day later | 0.84 | Still strong | | 3 days later | 0.50 | Half-life reached | | 7 days later | 0.21 | Fading | | 14 days later | 0.04 | **Forgotten** (score < 0.05) | ### Example: Watch a Memory Get Stronger Now let's say you mention "I prefer TypeScript" and then reference it 5 times over 2 weeks: | Action | Use Count | Score | |--------|-----------|-------| | Initial save | 1 | 1.00 | | Mention #2 | 2 | 1.55 | | Mention #3 | 3 | 1.93 | | Mention #4 | 4 | 2.23 | | Mention #5 | 5 | 2.49 | After use #5, the score is way above 0.65, so it gets **promoted to your Obsidian vault** as a permanent note. ## Storage: Where Are My Memories? ### Short-term (JSONL files) - **Location**: `~/.config/mnemex/jsonl/` (or whatever you set in `.env`) - **Files**: `memories.jsonl`, `relations.jsonl` - **Format**: Human-readable JSON, one memory per line - **Git-friendly**: You can version control these files! Example memory: ```json {"id":"mem-abc123","content":"I prefer TypeScript over JavaScript","tags":["preferences","typescript"],"created_at":"2025-10-07T10:00:00Z","last_used":"2025-10-07T10:00:00Z","use_count":1,"strength":1.0,"entities":["TypeScript","JavaScript"]} ``` ### Long-term (Markdown files) - **Location**: Your Obsidian vault (configurable in `.env`) - **Format**: Markdown files with YAML frontmatter - **Permanent**: Never forgotten unless you delete them Example promoted memory: ```markdown --- created: 2025-10-07 tags: [preferences, typescript, programming] entities: [TypeScript, JavaScript] --- # TypeScript Preference I prefer TypeScript over JavaScript for all new projects. **Related memories:** - [[Modern JavaScript Frameworks]] - [[Type Safety Best Practices]] ``` ## Commands You Can Use ```bash # Run the memory server for Claude mnemex # Search your memories from command line mnemex-search "typescript preferences" --tags preferences # Index your Obsidian vault for search mnemex-index-ltm # Check storage stats mnemex-maintenance stats # Clean up old memories (compact storage) mnemex-maintenance compact # Backup memories to git mnemex-backup snapshot ``` ## Tuning: Make It Work Your Way ### Fast-paced work (forget quickly) ```bash MNEMEX_PL_HALFLIFE_DAYS=1.0 # 1-day half-life MNEMEX_FORGET_THRESHOLD=0.10 # More aggressive forgetting ``` ### Research/archival (remember longer) ```bash MNEMEX_PL_HALFLIFE_DAYS=7.0 # 7-day half-life MNEMEX_FORGET_THRESHOLD=0.02 # Keep things longer ``` ### Preference-heavy assistant ```bash # Save preferences with higher importance # In your code: save_memory(..., strength=1.5) ``` ## FAQ **Q: Does this work with ChatGPT or other AI assistants?** A: This uses the Model Context Protocol (MCP), which is supported by most modern AI clients: - ✅ **Claude Desktop** - Full support - ✅ **CLI clients** (like Cline, Aider, etc.) - Full support - ✅ **Most desktop clients** - Full support - ⚠️ **ChatGPT** - Experimental MCP support only (not recommended yet) **Q: Will my memories get shared with Anthropic?** A: No. Everything is stored locally on your computer. Anthropic never sees your memories. **Q: What if I want to keep something forever?** A: Three ways: 1. **Use it frequently** so it gets auto-promoted 2. **Ask Claude directly**: "Never forget this..." or "Make a note that..." 3. **Set high strength manually** when saving (strength=1.5-2.0) **Q: Can I delete memories?** A: Yes. They're just JSONL files. Edit them manually or use the maintenance tools. **Q: What's this "knowledge graph" thing?** A: Memories can link to each other (like "TypeScript Preference" → "relates to" → "React Component Style"). You can query these relationships and find connections. **Q: Do I need Obsidian?** A: No! Obsidian integration is optional. You can use just short-term memory without any vault. **Q: This sounds complicated...** A: It's actually simple once it's set up: 1. Clone the repo 2. Install it 3. Add it to Claude's config (just the command, paths go in `.env`) 4. Restart Claude 5. Talk normally - memory "just works" ## What's Actually Novel Here? This isn't just "save stuff to a database." The key innovations: 1. **Temporal decay algorithm** - Mathematically modeled on how human memory works (Ebbinghaus forgetting curve) 2. **Smart prompting patterns** - Teaching Claude *when* to save/recall without explicit commands 3. **Two-layer architecture** - Automatic promotion from working memory to permanent storage 4. **Git-friendly storage** - Human-readable JSONL that you can version control Most importantly: **It feels natural.** You don't think about memory management. Claude just remembers things like a human would. ## Still Confused? Read the examples in the `examples/` directory or check out: - [docs/scoring_algorithm.md](docs/scoring_algorithm.md) - The math behind memory decay - [docs/architecture.md](docs/architecture.md) - How the system is built - [docs/api.md](docs/api.md) - All available commands ## TL;DR **One sentence**: Mnemex makes Claude remember things you tell it, with memories that fade naturally over time unless you use them frequently, just like human memory. **Quick start**: ```bash # Install uv tool install git+https://github.com/simplemindedbot/mnemex.git # Configure (optional - creates ~/.config/mnemex/.env) cp ~/.config/mnemex/.env.example ~/.config/mnemex/.env # Add to Claude config: {"command": "mnemex"} ``` Then restart Claude Desktop. Done.