Mnemex

A Model Context Protocol (MCP) server providinghuman-like memory dynamicsfor AI assistants. Memories naturally fade over time unless reinforced through use, mimicking theEbbinghaus forgetting curve.

This project was originally developed asmnemex(published to PyPI up to v0.6.0). In November 2025, it was transferred toPrefrontal Systemsand renamed toCortexGraphto better reflect its role within a broader cognitive architecture for AI systems.

[!IMPORTANT]🔬 RESEARCH ARTIFACT - NOT FOR PRODUCTION

This software is aProof of Concept (PoC)and reference implementation for research purposes. It exists to validate theoretical frameworks in cognitive architecture and AI safety (specifically theSTOPPER ProtocolandCortexGraph).

📖 New to this project?Start with theELI5 Guidefor a simple explanation of what this does and how to use it.

- 🧠Remembers what matters- Your preferences, decisions, and important facts
- ⏰Forgets naturally- Old, unused information fades away over time (like theEbbinghaus forgetting curve)
- 💪Gets stronger with use- The more you reference something, the longer it's remembered
- 📦Saves important things permanently- Frequently used memories get promoted to long-term storage
- You talk naturally- "I prefer dark mode in all my apps"
- Memory is saved automatically- No special commands needed
- Time passes- Memory gradually fades if not used
- You reference it again- "Make this app dark mode"
- Memory gets stronger- Now it lasts even longer
- Important memories promoted- Used 5+ times? Saved permanently to your Obsidian vault

- $\large n_{\text{use}}$ - Use count (number of accesses)
- $\large \beta$ (beta) - Sub-linear use count weighting (default: 0.6)
- $\large \lambda = \frac{\ln(2)}{t_{1/2}}$ (lambda) - Decay constant; set via half-life (default: 3-day)
- $\large \Delta t$ - Time since last access (seconds)
- $\large s$ - Strength parameter $\in [0, 2]$ (importance multiplier)

- $\large \tau_{\text{forget}}$ (default 0.05) — if score < this, forget
- $\large \tau_{\text{promote}}$ (default 0.65) — if score ≥ this, promote (or if $\large n_{\text{use}}\ge5$ in 14 days)

- Power‑Law (default): heavier tail; most human‑like retention
- Exponential: lighter tail; forgets sooner
- Two‑Component: fast early forgetting + heavier tail

See detailed parameter reference, model selection, and worked examples in docs/scoring_algorithm.md.

- Balanced (default)

- Half-life: 3 days (λ ≈ 2.67e-6)
- β = 0.6, τ_forget = 0.05, τ_promote = 0.65, use_count≥5 in 14d
- Strength: 1.0 (bump to 1.3–2.0 for critical)

- Half-life: 12–24 hours (λ ≈ 1.60e-5 to 8.02e-6)
- β = 0.8–0.9, τ_forget = 0.10–0.15, τ_promote = 0.70–0.75

- Half-life: 7–14 days (λ ≈ 1.15e-6 to 5.73e-7)
- β = 0.3–0.5, τ_forget = 0.02–0.05, τ_promote = 0.50–0.60

- Half-life: 3–7 days; β = 0.6–0.8
- Strength defaults: 1.3–1.5 for preferences; 1.8–2.0 for decisions

- Raise τ_forget to 0.08–0.12 and/or shorten half-life; schedule weekly GC

- CORTEXGRAPH_DECAY_LAMBDA=2.673e-6, CORTEXGRAPH_DECAY_BETA=0.6
- CORTEXGRAPH_FORGET_THRESHOLD=0.05, CORTEXGRAPH_PROMOTE_THRESHOLD=0.65
- CORTEXGRAPH_PROMOTE_USE_COUNT=5, CORTEXGRAPH_PROMOTE_TIME_WINDOW=14

- Forget: $\text{score} < 0.05$ → delete memory
- Promote: $\text{score} \geq 0.65$ OR $n_{\text{use}} \geq 5$ within 14 days → move to LTM

Unlike traditional caching (TTL, LRU), Mnemex scores memories continuously by combiningrecency(exponential decay),frequency(sub-linear use count), andimportance(adjustable strength). SeeCore Algorithmfor the mathematical formula. This creates memory dynamics that closely mimic human cognition.

# Before v0.6.0 - manual entity specification save_memory(content="Use JWT for auth", entities=["JWT", "auth"]) # v0.6.0+ - automatic extraction save_memory(content="Use JWT for auth") # Entities auto-extracted: ["jwt", "auth"] # Strength auto-calculated based on content

User: "Remember: I prefer TypeScript over JavaScript" → Detected save phrase: "Remember" → Automatically saved with: - Entities: [typescript, javascript] - Strength: 1.5 (importance marker detected) - Tags: [preferences, programming]

User: "What did I say about TypeScript?" → Detected recall phrase: "what did I say about" → Automatically searches for TypeScript memories → Retrieves preferences and conventions

User: "Yes, still using TypeScript" → Memory strength increased, decay slowed

Two new tools help Claude decide when to save/recall:

- analyze_message- Detects memory-worthy content, suggests entities and strength
- analyze_for_recall- Detects recall intent, suggests search queries

No explicit memory commands needed - just natural conversation.

Inspired 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).

No flashcards. No explicit review sessions. Just natural conversation.
- Review Priority Calculation- Memories in the "danger zone" (0.15-0.35 decay score) get highest priority
- Cross-Domain Detection- Detects when memories are used in different contexts (tag Jaccard similarity <30%)
- Automatic Reinforcement- Memories strengthen naturally when used, especially across domains
- Blended Search- Review candidates appear in 30% of search results (configurable)

User: "Can you help with authentication in my API?" → System searches, retrieves JWT preference memory → System uses memory to answer question → System calls observe_memory_usage with context tags [api, auth, backend] → Cross-domain usage detected (original tags: [security, jwt, preferences]) → Memory automatically reinforced, strength boosted → Next search naturally surfaces memories needing review

CORTEXGRAPH_REVIEW_BLEND_RATIO=0.3 # 30% review candidates in search CORTEXGRAPH_REVIEW_DANGER_ZONE_MIN=0.15 # Lower bound of danger zone CORTEXGRAPH_REVIEW_DANGER_ZONE_MAX=0.35 # Upper bound of danger zone CORTEXGRAPH_AUTO_REINFORCE=true # Auto-reinforce on observe

Seedocs/prompts/for LLM system prompt templates that enable natural memory usage.

graph TD STM["<b>Short-Term Memory</b><br/>- JSONL storage<br/>- Temporal decay<br/>- Hours to weeks retention"] LTM["<b>LTM (Long-Term Memory)</b><br/>- Markdown files Obsidian<br/>- Permanent storage<br/>- Git version control"] STM -->|Automatic promotion| LTM style STM fill:#e1f5ff,stroke:#01579b,stroke-width:2px style LTM fill:#f3e5f5,stroke:#4a148c,stroke-width:2px

Automated memory maintenance through five specialized agents:

graph LR decay["<b>DecayAnalyzer</b><br/>Find at-risk<br/>memories"] cluster["<b>ClusterDetector</b><br/>Find similar<br/>groups"] merge["<b>SemanticMerge</b><br/>Combine<br/>similar groups"] promote["<b>LTMPromoter</b><br/>Promote<br/>to LTM"] relations["<b>RelationshipDiscovery</b><br/>Discover cross-<br/>domain links"] decay --> cluster cluster --> merge merge --> promote promote --> relations relations -.->|feedback| decay style decay fill:#ffebee,stroke:#b71c1c,stroke-width:2px style cluster fill:#fff3e0,stroke:#e65100,stroke-width:2px style merge fill:#f3e5f5,stroke:#4a148c,stroke-width:2px style promote fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px style relations fill:#e1f5fe,stroke:#01579b,stroke-width:2px

- Dry-run mode: Preview changes without modifying data
- Rate limiting: Configurable operations per minute (default: 60)
- Audit trail: Every decision tracked via beads issue tracking
- Human override: Review and approve decisions before execution

from cortexgraph.agents import Scheduler # Preview what would change (dry run) scheduler = Scheduler(dry_run=True) preview = scheduler.run_pipeline() # Run full pipeline scheduler = Scheduler(dry_run=False) results = scheduler.run_pipeline() # Run single agent decay_results = scheduler.run_agent("decay")

# Dry run (preview) cortexgraph-consolidate --dry-run # Run specific agent cortexgraph-consolidate --agent decay --dry-run # Scheduled execution (with interval) cortexgraph-consolidate --scheduled --interval-hours 1

Seedocs/agents.mdfor complete documentation including configuration, beads integration, and troubleshooting.

# Install from PyPI (recommended - fast, isolated, includes all 7 CLI commands) uv tool install cortexgraph

# Using pipx (similar isolation to uv) pipx install cortexgraph # Using pip (traditional, installs in current environment) pip install cortexgraph # From GitHub (latest development version) uv tool install git+https://github.com/simplemindedbot/cortexgraph.git

# Clone and install in editable mode git clone https://github.com/simplemindedbot/cortexgraph.git cd cortexgraph uv pip install -e ".[dev]"

IMPORTANT: Configuration location depends on installation method:

Method 1: .env file (Works for all installation methods)

# Create config directory mkdir -p ~/.config/cortexgraph # Option A: Copy from cloned repo cp .env.example ~/.config/cortexgraph/.env # Option B: Download directly curl -o ~/.config/cortexgraph/.env https://raw.githubusercontent.com/simplemindedbot/cortexgraph/main/.env.example

Edit~/.config/cortexgraph/.envwith your settings:

# Storage CORTEXGRAPH_STORAGE_PATH=~/.config/cortexgraph/jsonl # Decay model (power_law | exponential | two_component) CORTEXGRAPH_DECAY_MODEL=power_law # Power-law parameters (default model) CORTEXGRAPH_PL_ALPHA=1.1 CORTEXGRAPH_PL_HALFLIFE_DAYS=3.0 # Exponential (if selected) # CORTEXGRAPH_DECAY_LAMBDA=2.673e-6 # 3-day half-life # Two-component (if selected) # CORTEXGRAPH_TC_LAMBDA_FAST=1.603e-5 # ~12h # CORTEXGRAPH_TC_LAMBDA_SLOW=1.147e-6 # ~7d # CORTEXGRAPH_TC_WEIGHT_FAST=0.7 # Common parameters CORTEXGRAPH_DECAY_LAMBDA=2.673e-6 CORTEXGRAPH_DECAY_BETA=0.6 # Thresholds CORTEXGRAPH_FORGET_THRESHOLD=0.05 CORTEXGRAPH_PROMOTE_THRESHOLD=0.65 # Long-term memory (optional) LTM_VAULT_PATH=~/Documents/Obsidian/Vault

- Primary:~/.config/cortexgraph/.env← Use this foruv tool install/uvx
- Fallback:./.env(current directory) ← Only works for editable installs

Recommended: Use absolute path (works everywhere)

Add to~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "cortexgraph": { "command": "/Users/yourusername/.local/bin/cortexgraph" } } }

which cortexgraph # Example output: /Users/yourusername/.local/bin/cortexgraph

Use that path in your config. Replaceyourusernamewith your actual username.