{
"markdown": "# CortexGraph: Temporal Memory for AI\n\n\n\nA Model Context Protocol (MCP) server providing **human-like memory dynamics** for AI assistants. Memories naturally fade over time unless reinforced through use, mimicking the [Ebbinghaus forgetting curve](https://en.wikipedia.org/wiki/Forgetting_curve).\n\n[](https://www.gnu.org/licenses/agpl-3.0)\n[](https://www.python.org/downloads/)\n[](https://github.com/prefrontal-systems/cortexgraph/actions/workflows/tests.yml)\n[](https://github.com/prefrontal-systems/cortexgraph/actions/workflows/security.yml)\n[](https://codecov.io/gh/prefrontal-systems/cortexgraph)\n[](https://github.com/prefrontal-systems/cortexgraph/actions/workflows/security.yml)\n\n> [!NOTE]\n> **About the Name & Version**\n>\n> This project was originally developed as **mnemex** (published to PyPI up to v0.6.0). In November 2025, it was transferred to [Prefrontal Systems](https://prefrontal.systems) and renamed to **CortexGraph** to better reflect its role within a broader cognitive architecture for AI systems.\n>\n> **Version numbering starts at 0.1.0** for the cortexgraph package to signal a fresh start under the new name, while acknowledging the mature, well-tested codebase (791 tests, 98%+ coverage) inherited from mnemex. The mnemex package remains frozen at v0.6.0 on PyPI.\n>\n> This versioning approach:\n> - Signals \"new package\" to PyPI users discovering cortexgraph\n> - Gives room to evolve the brand, API, and organizational integration before 1.0\n> - Maintains continuity: users can migrate from `pip install mnemex` → `pip install cortexgraph`\n> - Reflects that while the code is mature, the cortexgraph identity is just beginning\n\n> [!IMPORTANT]\n> **🔬 RESEARCH ARTIFACT - NOT FOR PRODUCTION**\n>\n> This software is a **Proof of Concept (PoC)** and reference implementation for research purposes. It exists to validate theoretical frameworks in cognitive architecture and AI safety (specifically the [STOPPER Protocol](https://prefrontal.systems/frameworks/stopper) and [CortexGraph](https://prefrontal.systems/frameworks/cortexgraph)).\n>\n> **It is NOT a commercial product.** It is not maintained for general production use, may contain breaking changes, and offers no guarantees of stability or support. Use it to study the concepts, but build your own production implementations.\n\n> **📖 New to this project?** Start with the [ELI5 Guide](ELI5.md) for a simple explanation of what this does and how to use it.\n\n## What is CortexGraph?\n\n**CortexGraph gives AI assistants like Claude a human-like memory system.**\n\n### The Problem\n\nWhen you chat with Claude, it forgets everything between conversations. You tell it \"I prefer TypeScript\" or \"I'm allergic to peanuts,\" and three days later, you have to repeat yourself. This is frustrating and wastes time.\n\n### What CortexGraph Does\n\nCortexGraph makes AI assistants **remember things naturally**, just like human memory:\n\n- 🧠 **Remembers what matters** - Your preferences, decisions, and important facts\n- ⏰ **Forgets naturally** - Old, unused information fades away over time (like the [Ebbinghaus forgetting curve](https://en.wikipedia.org/wiki/Forgetting_curve))\n- 💪 **Gets stronger with use** - The more you reference something, the longer it's remembered\n- 📦 **Saves important things permanently** - Frequently used memories get promoted to long-term storage\n\n### How It Works (Simple Version)\n\n1. **You talk naturally** - \"I prefer dark mode in all my apps\"\n2. **Memory is saved automatically** - No special commands needed\n3. **Time passes** - Memory gradually fades if not used\n4. **You reference it again** - \"Make this app dark mode\"\n5. **Memory gets stronger** - Now it lasts even longer\n6. **Important memories promoted** - Used 5+ times? Saved permanently to your Obsidian vault\n\n**No flashcards. No explicit review. Just natural conversation.**\n\n### Why It's Different\n\nMost memory systems are dumb:\n- ❌ \"Delete after 7 days\" (doesn't care if you used it 100 times)\n- ❌ \"Keep last 100 items\" (throws away important stuff just because it's old)\n\nCortexGraph is smart:\n- ✅ Combines **recency** (when?), **frequency** (how often?), and **importance** (how critical?)\n- ✅ Memories fade naturally like human memory\n- ✅ Frequently used memories stick around longer\n- ✅ You can mark critical things to \"never forget\"\n\n## Technical Overview\n\nThis repository contains research, design, and a complete implementation of a short-term memory system that combines:\n\n- **Novel temporal decay algorithm** based on cognitive science\n- **Reinforcement learning** through usage patterns\n- **Two-layer architecture** (STM + LTM) for working and permanent memory\n- **Smart prompting patterns** for natural LLM integration\n- **Git-friendly storage** with human-readable JSONL\n- **Knowledge graph** with entities and relations\n\n### Module Organization\n\nCortexGraph follows a modular architecture:\n\n- **`cortexgraph.core`**: Foundational algorithms (decay, similarity, clustering, consolidation, search validation)\n- **`cortexgraph.agents`**: Multi-agent consolidation pipeline and storage utilities\n- **`cortexgraph.storage`**: JSONL and SQLite storage backends with batch operations\n- **`cortexgraph.tools`**: MCP tool implementations\n\n## Why CortexGraph?\n\n### 🔒 Privacy & Transparency\n\n**All data stored locally on your machine** - no cloud services, no tracking, no data sharing.\n\n- **Short-term memory**:\n - **JSONL** (default): Human-readable, git-friendly files (`~/.config/cortexgraph/jsonl/`)\n - **SQLite**: Robust database storage for larger datasets (`~/.config/cortexgraph/cortexgraph.db`)\n\n- **Long-term memory**: Markdown files optimized for Obsidian\n - YAML frontmatter with metadata\n - Wikilinks for connections\n - Permanent storage you control\n\n- **Export**: Built-in utility to export memories to Markdown for portability.\n\nYou own your data. You can read it, edit it, delete it, or version control it - all without any special tools.\n\n## Core Algorithm\n\nThe temporal decay scoring function:\n\n$$\n\\Large \\text{score}(t) = (n_{\\text{use}})^\\beta \\cdot e^{-\\lambda \\cdot \\Delta t} \\cdot s\n$$\n\nWhere:\n\n- $\\large n_{\\text{use}}$ - Use count (number of accesses)\n- $\\large \\beta$ (beta) - Sub-linear use count weighting (default: 0.6)\n- $\\large \\lambda = \\frac{\\ln(2)}{t_{1/2}}$ (lambda) - Decay constant; set via half-life (default: 3-day)\n- $\\large \\Delta t$ - Time since last access (seconds)\n- $\\large s$ - Strength parameter $\\in [0, 2]$ (importance multiplier)\n\nThresholds:\n\n- $\\large \\tau_{\\text{forget}}$ (default 0.05) — if score < this, forget\n- $\\large \\tau_{\\text{promote}}$ (default 0.65) — if score ≥ this, promote (or if $\\large n_{\\text{use}}\\ge5$ in 14 days)\n\nDecay Models:\n\n- Power‑Law (default): heavier tail; most human‑like retention\n- Exponential: lighter tail; forgets sooner\n- Two‑Component: fast early forgetting + heavier tail\n\nSee detailed parameter reference, model selection, and worked examples in docs/scoring_algorithm.md.\n\n## Tuning Cheat Sheet\n\n- Balanced (default)\n - Half-life: 3 days (λ ≈ 2.67e-6)\n - β = 0.6, τ_forget = 0.05, τ_promote = 0.65, use_count≥5 in 14d\n - Strength: 1.0 (bump to 1.3–2.0 for critical)\n- High‑velocity context (ephemeral notes, rapid switching)\n - Half-life: 12–24 hours (λ ≈ 1.60e-5 to 8.02e-6)\n - β = 0.8–0.9, τ_forget = 0.10–0.15, τ_promote = 0.70–0.75\n- Long retention (research/archival)\n - Half-life: 7–14 days (λ ≈ 1.15e-6 to 5.73e-7)\n - β = 0.3–0.5, τ_forget = 0.02–0.05, τ_promote = 0.50–0.60\n- Preference/decision heavy assistants\n - Half-life: 3–7 days; β = 0.6–0.8\n - Strength defaults: 1.3–1.5 for preferences; 1.8–2.0 for decisions\n- Aggressive space control\n - Raise τ_forget to 0.08–0.12 and/or shorten half-life; schedule weekly GC\n- Environment template\n - CORTEXGRAPH_DECAY_LAMBDA=2.673e-6, CORTEXGRAPH_DECAY_BETA=0.6\n - CORTEXGRAPH_FORGET_THRESHOLD=0.05, CORTEXGRAPH_PROMOTE_THRESHOLD=0.65\n - CORTEXGRAPH_PROMOTE_USE_COUNT=5, CORTEXGRAPH_PROMOTE_TIME_WINDOW=14\n\n**Decision thresholds:**\n\n- Forget: $\\text{score} < 0.05$ → delete memory\n- Promote: $\\text{score} \\geq 0.65$ OR $n_{\\text{use}} \\geq 5$ within 14 days → move to LTM\n\n## Key Innovations\n\n### 1. Temporal Decay with Reinforcement\n\nUnlike traditional caching (TTL, LRU), Mnemex scores memories continuously by combining **recency** (exponential decay), **frequency** (sub-linear use count), and **importance** (adjustable strength). See [Core Algorithm](#core-algorithm) for the mathematical formula. This creates memory dynamics that closely mimic human cognition.\n\n### 2. Smart Prompting System + Natural Language Activation (v0.6.0+)\n\nPatterns for making AI assistants use memory naturally, now enhanced with **automatic entity extraction and importance scoring**:\n\n**Auto-Enrichment (NEW in v0.6.0)**\n\nWhen you save memories, CortexGraph automatically:\n- Extracts entities (people, technologies, organizations) using spaCy NER\n- Calculates importance/strength based on content markers\n- Detects save/recall intent from natural language phrases\n\n```python\n# Before v0.6.0 - manual entity specification\nsave_memory(content=\"Use JWT for auth\", entities=[\"JWT\", \"auth\"])\n\n# v0.6.0+ - automatic extraction\nsave_memory(content=\"Use JWT for auth\")\n# Entities auto-extracted: [\"jwt\", \"auth\"]\n# Strength auto-calculated based on content\n```\n\n**Auto-Save**\n\n```\nUser: \"Remember: I prefer TypeScript over JavaScript\"\n→ Detected save phrase: \"Remember\"\n→ Automatically saved with:\n - Entities: [typescript, javascript]\n - Strength: 1.5 (importance marker detected)\n - Tags: [preferences, programming]\n```\n\n**Auto-Recall**\n\n```\nUser: \"What did I say about TypeScript?\"\n→ Detected recall phrase: \"what did I say about\"\n→ Automatically searches for TypeScript memories\n→ Retrieves preferences and conventions\n```\n\n**Auto-Reinforce**\n\n```\nUser: \"Yes, still using TypeScript\"\n→ Memory strength increased, decay slowed\n```\n\n**Decision Support Tools (v0.6.0+)**\n\nTwo new tools help Claude decide when to save/recall:\n- `analyze_message` - Detects memory-worthy content, suggests entities and strength\n- `analyze_for_recall` - Detects recall intent, suggests search queries\n\nNo explicit memory commands needed - just natural conversation.\n\n### 3. Natural Spaced Repetition\n\nInspired by how concepts naturally reinforce across different contexts (the \"Maslow effect\" - remembering Maslow's hierarchy better when it appears in history, economics, and sociology classes).\n\n**No flashcards. No explicit review sessions. Just natural conversation.**\n\n**How it works:**\n\n1. **Review Priority Calculation** - Memories in the \"danger zone\" (0.15-0.35 decay score) get highest priority\n2. **Cross-Domain Detection** - Detects when memories are used in different contexts (tag Jaccard similarity <30%)\n3. **Automatic Reinforcement** - Memories strengthen naturally when used, especially across domains\n4. **Blended Search** - Review candidates appear in 30% of search results (configurable)\n\n**Usage pattern:**\n\n```\nUser: \"Can you help with authentication in my API?\"\n→ System searches, retrieves JWT preference memory\n→ System uses memory to answer question\n→ System calls observe_memory_usage with context tags [api, auth, backend]\n→ Cross-domain usage detected (original tags: [security, jwt, preferences])\n→ Memory automatically reinforced, strength boosted\n→ Next search naturally surfaces memories needing review\n```\n\n**Configuration:**\n\n```bash\nCORTEXGRAPH_REVIEW_BLEND_RATIO=0.3 # 30% review candidates in search\nCORTEXGRAPH_REVIEW_DANGER_ZONE_MIN=0.15 # Lower bound of danger zone\nCORTEXGRAPH_REVIEW_DANGER_ZONE_MAX=0.35 # Upper bound of danger zone\nCORTEXGRAPH_AUTO_REINFORCE=true # Auto-reinforce on observe\n```\n\nSee `docs/prompts/` for LLM system prompt templates that enable natural memory usage.\n\n### 4. Two-Layer Architecture\n\n```mermaid\ngraph TD\n STM[\"Short-Term Memory
- JSONL storage
- Temporal decay
- Hours to weeks retention\"]\n LTM[\"LTM (Long-Term Memory)
- Markdown files Obsidian
- Permanent storage
- Git version control\"]\n \n STM -->|Automatic promotion| LTM\n \n style STM fill:#e1f5ff,stroke:#01579b,stroke-width:2px\n style LTM fill:#f3e5f5,stroke:#4a148c,stroke-width:2px\n```\n\n### 5. Multi-Agent Consolidation Pipeline\n\nAutomated memory maintenance through five specialized agents:\n\n```mermaid\ngraph LR\n decay[\"DecayAnalyzer
Find at-risk
memories\"]\n cluster[\"ClusterDetector
Find similar
groups\"]\n merge[\"SemanticMerge
Combine
similar groups\"]\n promote[\"LTMPromoter
Promote
to LTM\"]\n relations[\"RelationshipDiscovery
Discover cross-
domain links\"]\n \n decay --> cluster\n cluster --> merge\n merge --> promote\n promote --> relations\n relations -.->|feedback| decay\n \n style decay fill:#ffebee,stroke:#b71c1c,stroke-width:2px\n style cluster fill:#fff3e0,stroke:#e65100,stroke-width:2px\n style merge fill:#f3e5f5,stroke:#4a148c,stroke-width:2px\n style promote fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px\n style relations fill:#e1f5fe,stroke:#01579b,stroke-width:2px\n```\n\n**The Five Agents:**\n\n| Agent | Purpose |\n|-------|---------|\n| **DecayAnalyzer** | Find memories at risk of being forgotten (danger zone: 0.15-0.35) |\n| **ClusterDetector** | Group similar memories using embedding similarity |\n| **SemanticMerge** | Intelligently combine clustered memories, preserving unique info |\n| **LTMPromoter** | Move high-value memories to permanent Obsidian storage |\n| **RelationshipDiscovery** | Find cross-domain connections via shared entities |\n\n**Key Features:**\n\n- **Dry-run mode**: Preview changes without modifying data\n- **Rate limiting**: Configurable operations per minute (default: 60)\n- **Audit trail**: Every decision tracked via beads issue tracking\n- **Human override**: Review and approve decisions before execution\n\n**Usage:**\n\n```python\nfrom cortexgraph.agents import Scheduler\n\n# Preview what would change (dry run)\nscheduler = Scheduler(dry_run=True)\npreview = scheduler.run_pipeline()\n\n# Run full pipeline\nscheduler = Scheduler(dry_run=False)\nresults = scheduler.run_pipeline()\n\n# Run single agent\ndecay_results = scheduler.run_agent(\"decay\")\n```\n\n**CLI:**\n\n```bash\n# Dry run (preview)\ncortexgraph-consolidate --dry-run\n\n# Run specific agent\ncortexgraph-consolidate --agent decay --dry-run\n\n# Scheduled execution (with interval)\ncortexgraph-consolidate --scheduled --interval-hours 1\n```\n\nSee [docs/agents.md](docs/agents.md) for complete documentation including configuration, beads integration, and troubleshooting.\n\n## Quick Start\n\n### Installation\n\n**Recommended: UV Tool Install (from PyPI)**\n\n```bash\n# Install from PyPI (recommended - fast, isolated, includes all 7 CLI commands)\nuv tool install cortexgraph\n```\n\nThis installs `cortexgraph` and all 7 CLI commands in an isolated environment.\n\n**Alternative Installation Methods**\n\n```bash\n# Using pipx (similar isolation to uv)\npipx install cortexgraph\n\n# Using pip (traditional, installs in current environment)\npip install cortexgraph\n\n# From GitHub (latest development version)\nuv tool install git+https://github.com/simplemindedbot/cortexgraph.git\n```\n\n**For Development (Editable Install)**\n\n```bash\n# Clone and install in editable mode\ngit clone https://github.com/simplemindedbot/cortexgraph.git\ncd cortexgraph\nuv pip install -e \".[dev]\"\n```\n\n### Configuration\n\n**IMPORTANT**: Configuration location depends on installation method:\n\n**Method 1: .env file (Works for all installation methods)**\n\nCreate `~/.config/cortexgraph/.env`:\n\n```bash\n# Create config directory\nmkdir -p ~/.config/cortexgraph\n\n# Option A: Copy from cloned repo\ncp .env.example ~/.config/cortexgraph/.env\n\n# Option B: Download directly\ncurl -o ~/.config/cortexgraph/.env https://raw.githubusercontent.com/simplemindedbot/cortexgraph/main/.env.example\n```\n\nEdit `~/.config/cortexgraph/.env` with your settings:\n\n```bash\n# Storage\nCORTEXGRAPH_STORAGE_PATH=~/.config/cortexgraph/jsonl\n\n# Decay model (power_law | exponential | two_component)\nCORTEXGRAPH_DECAY_MODEL=power_law\n\n# Power-law parameters (default model)\nCORTEXGRAPH_PL_ALPHA=1.1\nCORTEXGRAPH_PL_HALFLIFE_DAYS=3.0\n\n# Exponential (if selected)\n# CORTEXGRAPH_DECAY_LAMBDA=2.673e-6 # 3-day half-life\n\n# Two-component (if selected)\n# CORTEXGRAPH_TC_LAMBDA_FAST=1.603e-5 # ~12h\n# CORTEXGRAPH_TC_LAMBDA_SLOW=1.147e-6 # ~7d\n# CORTEXGRAPH_TC_WEIGHT_FAST=0.7\n\n# Common parameters\nCORTEXGRAPH_DECAY_LAMBDA=2.673e-6\nCORTEXGRAPH_DECAY_BETA=0.6\n\n# Thresholds\nCORTEXGRAPH_FORGET_THRESHOLD=0.05\nCORTEXGRAPH_PROMOTE_THRESHOLD=0.65\n\n# Long-term memory (optional)\nLTM_VAULT_PATH=~/Documents/Obsidian/Vault\n```\n\n**Where cortexgraph looks for .env files:**\n1. **Primary**: `~/.config/cortexgraph/.env` ← Use this for `uv tool install` / `uvx`\n2. **Fallback**: `./.env` (current directory) ← Only works for editable installs\n\n### MCP Configuration\n\n**Recommended: Use absolute path (works everywhere)**\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"cortexgraph\": {\n \"command\": \"/Users/yourusername/.local/bin/cortexgraph\"\n }\n }\n}\n```\n\n**Find your actual path:**\n\n```bash\nwhich cortexgraph\n# Example output: /Users/yourusername/.local/bin/cortexgraph\n```\n\nUse that path in your config. Replace `yourusername` with your actual username.\n\n**Why absolute path?** GUI apps like Claude Desktop don't inherit your shell's PATH configuration (`.zshrc`, `.bashrc`). Using the full path ensures it always works.\n\n**For development (editable install):**\n\n```json\n{\n \"mcpServers\": {\n \"cortexgraph\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"/path/to/cortexgraph\", \"run\", \"cortexgraph\"],\n \"env\": {\"PYTHONPATH\": \"/path/to/cortexgraph/src\"}\n }\n }\n}\n```\n\nConfiguration can be loaded from `./.env` in the project directory OR `~/.config/cortexgraph/.env`.\n\n#### Troubleshooting: Command Not Found\n\nIf Claude Desktop shows `spawn cortexgraph ENOENT` errors, the `cortexgraph` command isn't in Claude Desktop's PATH.\n\n**macOS/Linux: GUI apps don't inherit shell PATH**\n\nGUI applications on macOS and Linux don't see your shell's PATH configuration (`.zshrc`, `.bashrc`, etc.). Claude Desktop only searches:\n- `/usr/local/bin`\n- `/opt/homebrew/bin` (macOS)\n- `/usr/bin`\n- `/bin`\n- `/usr/sbin`\n- `/sbin`\n\nIf `uv tool install` placed `cortexgraph` in `~/.local/bin/` or another custom location, Claude Desktop can't find it.\n\n**Solution: Use absolute path**\n\n```bash\n# Find where cortexgraph is installed\nwhich cortexgraph\n# Example output: /Users/username/.local/bin/cortexgraph\n```\n\nUpdate your Claude config with the absolute path:\n\n```json\n{\n \"mcpServers\": {\n \"cortexgraph\": {\n \"command\": \"/Users/username/.local/bin/cortexgraph\"\n }\n }\n}\n```\n\nReplace `/Users/username/.local/bin/cortexgraph` with your actual path from `which cortexgraph`.\n### Maintenance\n\nUse the maintenance CLI to inspect and compact JSONL storage:\n\n```bash\n# Show storage stats (active counts, file sizes, compaction hints)\ncortexgraph-maintenance stats\n\n# Compact JSONL (rewrite without tombstones/duplicates)\ncortexgraph-maintenance compact\n```\n\n### Migrating to UV Tool Install\n\nIf you're currently using an editable install (`uv pip install -e .`), you can switch to the simpler UV tool install:\n\n```bash\n# 1. Uninstall editable version\nuv pip uninstall cortexgraph\n\n# 2. Install as UV tool\nuv tool install git+https://github.com/simplemindedbot/cortexgraph.git\n\n# 3. Update Claude Desktop config to just:\n# {\"command\": \"cortexgraph\"}\n# Remove the --directory, run, and PYTHONPATH settings\n```\n\n**Your data is safe!** This only changes how the command is installed. Your memories in `~/.config/cortexgraph/` are untouched.\n\n## CLI Commands\n\nThe server includes 7 command-line tools:\n\n```bash\ncortexgraph # Run MCP server\ncortexgraph-migrate # Migrate from old STM setup\ncortexgraph-index-ltm # Index Obsidian vault\ncortexgraph-backup # Git backup operations\ncortexgraph-vault # Vault markdown operations\ncortexgraph-search # Unified STM+LTM search\ncortexgraph-maintenance # JSONL storage stats and compaction\n```\n\n## Visualization\n\nInteractive graph visualization using PyVis:\n\n```bash\n# Install visualization dependencies\npip install \"cortexgraph[visualization]\"\n# or with uv\nuv pip install \"cortexgraph[visualization]\"\n\n# Or install dependencies manually\npip install pyvis networkx\n\n# Generate interactive HTML visualization\npython scripts/visualize_graph.py\n\n# Custom output location\npython scripts/visualize_graph.py --output ~/Desktop/memory_graph.html\n\n# Custom data paths\npython scripts/visualize_graph.py --memories ~/data/memories.jsonl --relations ~/data/relations.jsonl\n```\n\n**Features:**\n- Interactive network graph with pan/zoom\n- Node colors by status (active=blue, promoted=green, archived=gray)\n- Node size based on use count\n- Edge colors by relation type\n- Hover tooltips showing full content, tags, and entities\n- Physics controls for layout adjustment\n\nThe visualization reads directly from your JSONL files and creates a standalone HTML file you can open in any browser.\n\n## MCP Tools\n\n13 tools for AI assistants to manage memories:\n\n| Tool | Purpose |\n|------|---------|\n| `save_memory` | Save new memory with tags, entities (auto-enrichment in v0.6.0+) |\n| `search_memory` | Search with filters and scoring (includes review candidates) |\n| `search_unified` | Unified search across STM + LTM |\n| `touch_memory` | Reinforce memory (boost strength) |\n| `observe_memory_usage` | Record memory usage for natural spaced repetition |\n| `analyze_message` | ✨ **NEW v0.6.0** - Detect memory-worthy content, suggest entities/strength |\n| `analyze_for_recall` | ✨ **NEW v0.6.0** - Detect recall intent, suggest search queries |\n| `gc` | Garbage collect low-scoring memories |\n| `promote_memory` | Move to long-term storage |\n| `cluster_memories` | Find similar memories |\n| `consolidate_memories` | Merge similar memories (algorithmic) |\n| `read_graph` | Get entire knowledge graph |\n| `open_memories` | Retrieve specific memories |\n| `create_relation` | Link memories explicitly |\n\n### Example: Unified Search\n\nSearch across STM and LTM with the CLI:\n\n```bash\ncortexgraph-search \"typescript preferences\" --tags preferences --limit 5 --verbose\n```\n\n### Example: Reinforce (Touch) Memory\n\nBoost a memory's recency/use count to slow decay:\n\n```json\n{\n \"memory_id\": \"mem-123\",\n \"boost_strength\": true\n}\n```\n\nSample response:\n\n```json\n{\n \"success\": true,\n \"memory_id\": \"mem-123\",\n \"old_score\": 0.41,\n \"new_score\": 0.78,\n \"use_count\": 5,\n \"strength\": 1.1\n}\n```\n\n### Example: Promote Memory\n\nSuggest and promote high-value memories to the Obsidian vault.\n\nAuto-detect (dry run):\n\n```json\n{\n \"auto_detect\": true,\n \"dry_run\": true\n}\n```\n\nPromote a specific memory:\n\n```json\n{\n \"memory_id\": \"mem-123\",\n \"dry_run\": false,\n \"target\": \"obsidian\"\n}\n```\n\nAs an MCP tool (request body):\n\n```json\n{\n \"query\": \"typescript preferences\",\n \"tags\": [\"preferences\"],\n \"limit\": 5,\n \"verbose\": true\n}\n```\n\n### Example: Consolidate Similar Memories\n\nFind and merge duplicate or highly similar memories to reduce clutter:\n\nAuto-detect candidates (preview):\n\n```json\n{\n \"auto_detect\": true,\n \"mode\": \"preview\",\n \"cohesion_threshold\": 0.75\n}\n```\n\nApply consolidation to detected clusters:\n\n```json\n{\n \"auto_detect\": true,\n \"mode\": \"apply\",\n \"cohesion_threshold\": 0.80\n}\n```\n\nThe tool will:\n- Merge content intelligently (preserving unique information)\n- Combine tags and entities (union)\n- Calculate strength based on cluster cohesion\n- Preserve earliest `created_at` and latest `last_used` timestamps\n- Create tracking relations showing consolidation history\n\n## Mathematical Details\n\n### Decay Curves\n\nFor a memory with $n_{\\text{use}}=1$, $s=1.0$, and $\\lambda = 2.673 \\times 10^{-6}$ (3-day half-life):\n\n| Time | Score | Status |\n|------|-------|--------|\n| 0 hours | 1.000 | Fresh |\n| 12 hours | 0.917 | Active |\n| 1 day | 0.841 | Active |\n| 3 days | 0.500 | Half-life |\n| 7 days | 0.210 | Decaying |\n| 14 days | 0.044 | Near forget |\n| 30 days | 0.001 | **Forgotten** |\n\n### Use Count Impact\n\nWith $\\beta = 0.6$ (sub-linear weighting):\n\n| Use Count | Boost Factor |\n|-----------|--------------|\n| 1 | 1.0× |\n| 5 | 2.6× |\n| 10 | 4.0× |\n| 50 | 11.4× |\n\nFrequent access significantly extends retention.\n\n## Documentation\n\n- **[MCP Tools Reference](docs/mcp-tools.md)** - Comprehensive documentation for all 18 MCP tools\n- **[API Quick Reference](docs/api.md)** - Minimal tool signatures and usage examples\n- **[Scoring Algorithm](docs/scoring_algorithm.md)** - Complete mathematical model with LaTeX formulas\n- **[Smart Prompting](docs/prompts/memory_system_prompt.md)** - Patterns for natural LLM integration\n- **[Architecture](docs/architecture.md)** - System design and implementation\n- **[Multi-Agent System](docs/agents.md)** - Consolidation agents and pipeline architecture\n- **[Bear Integration](docs/bear-integration.md)** - Guide to using Bear app as an LTM store\n- **[Graph Features](docs/graph_features.md)** - Knowledge graph usage\n\n## Use Cases\n\n### Personal Assistant (Balanced)\n\n- 3-day half-life\n- Remember preferences and decisions\n- Auto-promote frequently referenced information\n\n### Development Environment (Aggressive)\n\n- 1-day half-life\n- Fast context switching\n- Aggressive forgetting of old context\n\n### Research / Archival (Conservative)\n\n- 14-day half-life\n- Long retention\n- Comprehensive knowledge preservation\n\n## License\n\nAGPL-3.0 License - See [LICENSE](LICENSE) for details.\n\nThis project uses the GNU Affero General Public License v3.0, which requires that modifications to this software be made available as source code when used to provide a network service.\n\n## Related Work\n\n- [Model Context Protocol](https://github.com/modelcontextprotocol) - MCP specification\n- [Ebbinghaus Forgetting Curve](https://en.wikipedia.org/wiki/Forgetting_curve) - Cognitive science foundation\n- [Basic Memory](https://github.com/basicmachines-co/basic-memory) - Primary inspiration for the integration layer. CortexGraph extends this concept by adding the Ebbinghaus forgetting curve, temporal decay algorithms, short-term memory in JSONL storage, and natural spaced repetition.\n- Additional research inspired by: mem0, Neo4j Graph Memory\n\n## Citation\n\nIf you use this work in research, please cite:\n\n```bibtex\n@software{cortexgraph_2025,\n title = {Mnemex: Temporal Memory for AI},\n author = {simplemindedbot},\n year = {2025},\n url = {https://github.com/simplemindedbot/cortexgraph},\n version = {0.5.3}\n}\n```\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions.\n\n### 🚨 **Help Needed: Windows & Linux Testers!**\n\nI develop on macOS and need help testing on Windows and Linux. If you have access to these platforms, please:\n\n- Try the installation instructions\n- Run the test suite\n- Report what works and what doesn't\n\nSee the [**Help Needed section**](CONTRIBUTING.md#-help-needed-windows--linux-testers) in CONTRIBUTING.md for details.\n\n### General Contributions\n\nFor all contributors, see [CONTRIBUTING.md](CONTRIBUTING.md) for:\n\n- Platform-specific setup (Windows, Linux, macOS)\n- Development workflow\n- Testing guidelines\n- Code style requirements\n- Pull request process\n\nQuick start:\n\n1. Read [CONTRIBUTING.md](CONTRIBUTING.md) for platform-specific setup\n2. Understand the [Architecture docs](docs/architecture.md)\n3. Review the [Scoring Algorithm](docs/scoring_algorithm.md)\n4. Follow existing code patterns\n5. Add tests for new features\n6. Update documentation\n\n## Status\n\n**Version:** 1.0.0\n**Status:** Research implementation - functional but evolving\n\n### Phase 1 (Complete) ✅\n\n- 14 MCP tools\n- Temporal decay algorithm\n- Knowledge graph\n\n### Phase 2 (Complete) ✅\n\n- JSONL storage\n- LTM index\n- Git integration\n- Smart prompting documentation\n- Maintenance CLI\n- Memory consolidation (algorithmic merging)\n\n### Phase 3 (Complete) ✅\n\n- **Multi-Agent Consolidation Pipeline**\n - DecayAnalyzer, ClusterDetector, SemanticMerge, LTMPromoter, RelationshipDiscovery\n - Scheduler for orchestration\n - Beads issue tracking integration\n - Dry-run and rate limiting support\n- Natural language activation (v0.6.0+)\n- Auto-enrichment for entity extraction\n\n### Future Work\n\n- Adaptive decay parameters\n- Performance benchmarks\n- LLM-assisted consolidation (optional enhancement)\n\n---\n\n**Built with** [Claude Code](https://claude.com/claude-code) 🤖\n",
"bytes": 29114,
"sha": "017ed5be51f0208283b7aa8198daca2d926ff2620f3142ecffa17f1ad6d953c2",
"repo_slug": "simplemindedbot/mnemex",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_simplemindedbot_mnemex_3fa714af/readme"
}