시간적 감쇠와 강화 학습을 사용하여 단기 및 장기 정보를 관리하는 인간과 유사한 메모리 시스템을 AI 어시스턴트에게 제공합니다.
다른 이름 simplemindedbot/mnemex
- 스타
- 39
- Tools
- 13
- 다운로드, 30일
- 16
- 최신 버전
- 0.5.2
- 마지막 커밋
- 2026년 11월 8일
- 라이선스
- AGPL-3.0
CortexGraph MCP란?
시간적 감쇠와 강화 학습을 사용하여 단기 및 장기 정보를 관리하는 인간과 유사한 메모리 시스템을 AI 어시스턴트에게 제공합니다. 13개 도구를 제공합니다. 예: save_memory, search_memory, search_unified.
프로젝트 README에서 생성된 요약
CortexGraph MCP server 정보
이전 명칭이 mnemex였던 CortexGraph는 인간의 학습 역학을 모방한 인지 메모리 시스템을 AI 어시스턴트에게 제공합니다. 에빙하우스 망각 곡선에 기반한 시간적 감쇠 알고리즘을 사용하여, 사용되지 않는 정보는 시간이 지남에 따라 자연스럽게 사라지게 하고 자주 참조되는 사실은 더욱 강화되도록 합니다. 이 시스템은 상용 제품이 아닌 개념 증명 단계로, 인지 아키텍처와 AI safety를 연구하는 연구자들을 위해 설계되었습니다.
사용자는 명시적인 명령 없이 자연스러운 대화를 통해 서버와 상호작용합니다. 시스템은 두 가지 계층의 메모리를 관리합니다. 로컬 저장소로 JSONL 또는 SQLite를 사용하는 단기 계층과, 중요한 정보를 Obsidian에서 사용할 수 있도록 Markdown 파일로 승격시키는 장기 계층이 있습니다. 또한 자동 엔티티 추출 및 중요도 점수 산정 기능을 갖추고 있어 어시스턴트가 무엇을 기억할지 결정하는 데 도움을 줍니다. 모든 데이터는 사용자의 로컬 머신에만 머무르며, 사람이 읽을 수 있는 저장 형식을 통해 프라이버시와 투명성을 보장합니다.
활용 사례
- 1선호도 유지 자동화AI 어시스턴트가 서로 다른 채팅 세션 전반에 걸쳐 프로그래밍 언어 선택과 같은 사용자의 특정 선호도를 기억할 수 있습니다.
- 2사용을 통한 중요 사실 강화사용자가 대화 중에 특정 메모리를 참조할 때마다 시스템이 해당 메모리의 강도를 높입니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
CortexGraph MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 CortexGraph MCP 설치
$ claude mcp add mnemex -- uvx mnemexCursor에 CortexGraph MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"mnemex": {
"command": "uvx",
"args": [
"mnemex"
]
}
}
}VS Code에 CortexGraph MCP 설치
.vscode/mcp.json
{
"servers": {
"mnemex": {
"type": "stdio",
"command": "uvx",
"args": [
"mnemex"
]
}
}
}VS Code CLI에 CortexGraph MCP 설치
$ code --add-mcp '{"name":"mnemex","type":"stdio","command":"uvx","args":["mnemex"]}'Claude Desktop에 CortexGraph MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"mnemex": {
"command": "uvx",
"args": [
"mnemex"
]
}
}
}Codex에 CortexGraph MCP 설치
$ codex mcp add mnemex -- uvx mnemexCodex config.toml에 CortexGraph MCP 설치
~/.codex/config.toml
[mcp_servers.mnemex] command = "uvx" args = ["mnemex"]
Gemini CLI에 CortexGraph MCP 설치
$ gemini mcp add -s user mnemex uvx -- mnemexGemini settings.json에 CortexGraph MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"mnemex": {
"command": "uvx",
"args": [
"mnemex"
]
}
}
}CortexGraph MCP 도구 13
README에서 감지됨save_memorysearch_memorysearch_unifiedtouch_memoryobserve_memory_usageanalyze_messageanalyze_for_recallpromote_memorycluster_memoriesconsolidate_memoriesread_graphopen_memories
| save_memory | — | |
| search_memory | — | |
| search_unified | — | |
| touch_memory | — | |
| observe_memory_usage | — | |
| analyze_message | — | |
| analyze_for_recall | — | |
| promote_memory | — | |
| cluster_memories | — | |
| consolidate_memories | — | |
| read_graph | — | |
| open_memories | — |
도구 13개 모두 보기도구 수 줄이기
create_relation
| create_relation | — |
구성
CORTEXGRAPH_AUTO_REINFORCECORTEXGRAPH_DECAY_BETACORTEXGRAPH_DECAY_LAMBDACORTEXGRAPH_DECAY_MODELCORTEXGRAPH_FORGET_THRESHOLDCORTEXGRAPH_PL_ALPHACORTEXGRAPH_PL_HALFLIFE_DAYSCORTEXGRAPH_PROMOTE_THRESHOLDCORTEXGRAPH_REVIEW_BLEND_RATIOCORTEXGRAPH_REVIEW_DANGER_ZONE_MAXCORTEXGRAPH_REVIEW_DANGER_ZONE_MINCORTEXGRAPH_STORAGE_PATHLTM_VAULT_PATHPath to Obsidian vault for long-term memory
MNEMEX_DECAY_MODELDecay model: power_law (default), exponential, or two_component
MNEMEX_PL_HALFLIFE_DAYSHalf-life in days for power-law decay model
MNEMEX_STORAGE_PATHStorage path for short-term memory JSONL files
| 이름 | 설명 | 유형 |
|---|---|---|
| CORTEXGRAPH_AUTO_REINFORCE | — | |
| CORTEXGRAPH_DECAY_BETA | — | |
| CORTEXGRAPH_DECAY_LAMBDA | — | |
| CORTEXGRAPH_DECAY_MODEL | — | |
| CORTEXGRAPH_FORGET_THRESHOLD | — | |
| CORTEXGRAPH_PL_ALPHA | — | |
| CORTEXGRAPH_PL_HALFLIFE_DAYS | — | |
| CORTEXGRAPH_PROMOTE_THRESHOLD | — | |
| CORTEXGRAPH_REVIEW_BLEND_RATIO | — | |
| CORTEXGRAPH_REVIEW_DANGER_ZONE_MAX | — | |
| CORTEXGRAPH_REVIEW_DANGER_ZONE_MIN | — | |
| CORTEXGRAPH_STORAGE_PATH | — | |
| LTM_VAULT_PATH | Path to Obsidian vault for long-term memory | |
| MNEMEX_DECAY_MODEL | Decay model: power_law (default), exponential, or two_component | |
| MNEMEX_PL_HALFLIFE_DAYS | Half-life in days for power-law decay model | |
| MNEMEX_STORAGE_PATH | Storage path for short-term memory JSONL files |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨통과
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기CortexGraph: Temporal Memory for AI
A 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.
[!NOTE] About the Name & Version
This project was originally developed as mnemex (published to PyPI up to v0.6.0). In November 2025, it was transferred to Prefrontal Systems and renamed to CortexGraph to better reflect its role within a broader cognitive architecture for AI systems.
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.
This versioning approach:
- Signals "new package" to PyPI users discovering cortexgraph
- Gives room to evolve the brand, API, and organizational integration before 1.0
- Maintains continuity: users can migrate from
pip install mnemex→pip install cortexgraph- Reflects that while the code is mature, the cortexgraph identity is just beginning
[!IMPORTANT] 🔬 RESEARCH ARTIFACT - NOT FOR PRODUCTION
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 and CortexGraph).
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.
📖 New to this project? Start with the ELI5 Guide for a simple explanation of what this does and how to use it.
What is CortexGraph?
CortexGraph gives AI assistants like Claude a human-like memory system.
The Problem
When 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.
What CortexGraph Does
CortexGraph makes AI assistants remember things naturally, just like human memory:
- 🧠 Remembers what matters - Your preferences, decisions, and important facts
- ⏰ Forgets naturally - Old, unused information fades away over time (like the Ebbinghaus 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
How It Works (Simple Version)
- 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
No flashcards. No explicit review. Just natural conversation.
Why It's Different
Most memory systems are dumb:
- ❌ "Delete after 7 days" (doesn't care if you used it 100 times)
- ❌ "Keep last 100 items" (throws away important stuff just because it's old)
CortexGraph is smart:
- ✅ Combines recency (when?), frequency (how often?), and importance (how critical?)
- ✅ Memories fade naturally like human memory
- ✅ Frequently used memories stick around longer
- ✅ You can mark critical things to "never forget"
Technical Overview
This repository contains research, design, and a complete implementation of a short-term memory system that combines:
- Novel temporal decay algorithm based on cognitive science
- Reinforcement learning through usage patterns
- Two-layer architecture (STM + LTM) for working and permanent memory
- Smart prompting patterns for natural LLM integration
- Git-friendly storage with human-readable JSONL
- Knowledge graph with entities and relations
Module Organization
CortexGraph follows a modular architecture:
cortexgraph.core: Foundational algorithms (decay, similarity, clustering, consolidation, search validation)cortexgraph.agents: Multi-agent consolidation pipeline and storage utilitiescortexgraph.storage: JSONL and SQLite storage backends with batch operationscortexgraph.tools: MCP tool implementations
Why CortexGraph?
🔒 Privacy & Transparency
All data stored locally on your machine - no cloud services, no tracking, no data sharing.
-
Short-term memory:
- JSONL (default): Human-readable, git-friendly files (
~/.config/cortexgraph/jsonl/) - SQLite: Robust database storage for larger datasets (
~/.config/cortexgraph/cortexgraph.db)
- JSONL (default): Human-readable, git-friendly files (
-
Long-term memory: Markdown files optimized for Obsidian
- YAML frontmatter with metadata
- Wikilinks for connections
- Permanent storage you control
-
Export: Built-in utility to export memories to Markdown for portability.
You own your data. You can read it, edit it, delete it, or version control it - all without any special tools.
Core Algorithm
The temporal decay scoring function:
$$ \Large \text{score}(t) = (n_{\text{use}})^\beta \cdot e^{-\lambda \cdot \Delta t} \cdot s $$
Where:
- $\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)
Thresholds:
- $\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)
Decay Models:
- 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.
Tuning Cheat Sheet
- 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)
- High‑velocity context (ephemeral notes, rapid switching)
- 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
- Long retention (research/archival)
- 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
- Preference/decision heavy assistants
- Half-life: 3–7 days; β = 0.6–0.8
- Strength defaults: 1.3–1.5 for preferences; 1.8–2.0 for decisions
- Aggressive space control
- Raise τ_forget to 0.08–0.12 and/or shorten half-life; schedule weekly GC
- Environment template
- 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
Decision thresholds:
- 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
Key Innovations
1. Temporal Decay with Reinforcement
Unlike 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 for the mathematical formula. This creates memory dynamics that closely mimic human cognition.
2. Smart Prompting System + Natural Language Activation (v0.6.0+)
Patterns for making AI assistants use memory naturally, now enhanced with automatic entity extraction and importance scoring:
Auto-Enrichment (NEW in v0.6.0)
When you save memories, CortexGraph automatically:
- Extracts entities (people, technologies, organizations) using spaCy NER
- Calculates importance/strength based on content markers
- Detects save/recall intent from natural language phrases
# 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
Auto-Save
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]
Auto-Recall
User: "What did I say about TypeScript?"
→ Detected recall phrase: "what did I say about"
→ Automatically searches for TypeScript memories
→ Retrieves preferences and conventions
Auto-Reinforce
User: "Yes, still using TypeScript"
→ Memory strength increased, decay slowed
Decision Support Tools (v0.6.0+)
Two new tools help Claude decide when to save/recall:
analyze_message- Detects memory-worthy content, suggests entities and strengthanalyze_for_recall- Detects recall intent, suggests search queries
No explicit memory commands needed - just natural conversation.
3. Natural Spaced Repetition
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.
How it works:
- 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)
Usage pattern:
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
Configuration:
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
See docs/prompts/ for LLM system prompt templates that enable natural memory usage.
4. Two-Layer Architecture
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
5. Multi-Agent Consolidation Pipeline
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
The Five Agents:
| Agent | Purpose |
|---|---|
| DecayAnalyzer | Find memories at risk of being forgotten (danger zone: 0.15-0.35) |
| ClusterDetector | Group similar memories using embedding similarity |
| SemanticMerge | Intelligently combine clustered memories, preserving unique info |
| LTMPromoter | Move high-value memories to permanent Obsidian storage |
| RelationshipDiscovery | Find cross-domain connections via shared entities |
Key Features:
- 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
Usage:
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")
CLI:
# 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
See docs/agents.md for complete documentation including configuration, beads integration, and troubleshooting.
Quick Start
Installation
Recommended: UV Tool Install (from PyPI)
# Install from PyPI (recommended - fast, isolated, includes all 7 CLI commands)
uv tool install cortexgraph
This installs cortexgraph and all 7 CLI commands in an isolated environment.
Alternative Installation Methods
# 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
For Development (Editable Install)
# Clone and install in editable mode
git clone https://github.com/simplemindedbot/cortexgraph.git
cd cortexgraph
uv pip install -e ".[dev]"
Configuration
IMPORTANT: Configuration location depends on installation method:
Method 1: .env file (Works for all installation methods)
Create ~/.config/cortexgraph/.env:
# 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/.env with 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
Where cortexgraph looks for .env files:
- Primary:
~/.config/cortexgraph/.env← Use this foruv tool install/uvx - Fallback:
./.env(current directory) ← Only works for editable installs
MCP Configuration
Recommended: Use absolute path (works everywhere)
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"cortexgraph": {
"command": "/Users/yourusername/.local/bin/cortexgraph"
}
}
}
Find your actual path:
which cortexgraph
# Example output: /Users/yourusername/.local/bin/cortexgraph
Use that path in your config. Replace yourusername with your actual username.
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.
For development (editable install):
{
"mcpServers": {
"cortexgraph": {
"command": "uv",
"args": ["--directory", "/path/to/cortexgraph", "run", "cortexgraph"],
"env": {"PYTHONPATH": "/path/to/cortexgraph/src"}
}
}
}
Configuration can be loaded from ./.env in the project directory OR ~/.config/cortexgraph/.env.
Troubleshooting: Command Not Found
If Claude Desktop shows spawn cortexgraph ENOENT errors, the cortexgraph command isn't in Claude Desktop's PATH.
macOS/Linux: GUI apps don't inherit shell PATH
GUI applications on macOS and Linux don't see your shell's PATH configuration (.zshrc, .bashrc, etc.). Claude Desktop only searches:
/usr/local/bin/opt/homebrew/bin(macOS)/usr/bin/bin/usr/sbin/sbin
If uv tool install placed cortexgraph in ~/.local/bin/ or another custom location, Claude Desktop can't find it.
Solution: Use absolute path
# Find where cortexgraph is installed
which cortexgraph
# Example output: /Users/username/.local/bin/cortexgraph
Update your Claude config with the absolute path:
{
"mcpServers": {
"cortexgraph": {
"command": "/Users/username/.local/bin/cortexgraph"
}
}
}
Replace /Users/username/.local/bin/cortexgraph with your actual path from which cortexgraph.
Maintenance
Use the maintenance CLI to inspect and compact JSONL storage:
# Show storage stats (active counts, file sizes, compaction hints)
cortexgraph-maintenance stats
# Compact JSONL (rewrite without tombstones/duplicates)
cortexgraph-maintenance compact
Migrating to UV Tool Install
If you're currently using an editable install (uv pip install -e .), you can switch to the simpler UV tool install:
# 1. Uninstall editable version
uv pip uninstall cortexgraph
# 2. Install as UV tool
uv tool install git+https://github.com/simplemindedbot/cortexgraph.git
# 3. Update Claude Desktop config to just:
# {"command": "cortexgraph"}
# Remove the --directory, run, and PYTHONPATH settings
Your data is safe! This only changes how the command is installed. Your memories in ~/.config/cortexgraph/ are untouched.
CLI Commands
The server includes 7 command-line tools:
cortexgraph # Run MCP server
cortexgraph-migrate # Migrate from old STM setup
cortexgraph-index-ltm # Index Obsidian vault
cortexgraph-backup # Git backup operations
cortexgraph-vault # Vault markdown operations
cortexgraph-search # Unified STM+LTM search
cortexgraph-maintenance # JSONL storage stats and compaction
Visualization
Interactive graph visualization using PyVis:
# Install visualization dependencies
pip install "cortexgraph[visualization]"
# or with uv
uv pip install "cortexgraph[visualization]"
# Or install dependencies manually
pip install pyvis networkx
# Generate interactive HTML visualization
python scripts/visualize_graph.py
# Custom output location
python scripts/visualize_graph.py --output ~/Desktop/memory_graph.html
# Custom data paths
python scripts/visualize_graph.py --memories ~/data/memories.jsonl --relations ~/data/relations.jsonl
Features:
- Interactive network graph with pan/zoom
- Node colors by status (active=blue, promoted=green, archived=gray)
- Node size based on use count
- Edge colors by relation type
- Hover tooltips showing full content, tags, and entities
- Physics controls for layout adjustment
The visualization reads directly from your JSONL files and creates a standalone HTML file you can open in any browser.
MCP Tools
13 tools for AI assistants to manage memories:
| Tool | Purpose |
|---|---|
save_memory |
Save new memory with tags, entities (auto-enrichment in v0.6.0+) |
search_memory |
Search with filters and scoring (includes review candidates) |
search_unified |
Unified search across STM + LTM |
touch_memory |
Reinforce memory (boost strength) |
observe_memory_usage |
Record memory usage for natural spaced repetition |
analyze_message |
✨ NEW v0.6.0 - Detect memory-worthy content, suggest entities/strength |
analyze_for_recall |
✨ NEW v0.6.0 - Detect recall intent, suggest search queries |
gc |
Garbage collect low-scoring memories |
promote_memory |
Move to long-term storage |
cluster_memories |
Find similar memories |
consolidate_memories |
Merge similar memories (algorithmic) |
read_graph |
Get entire knowledge graph |
open_memories |
Retrieve specific memories |
create_relation |
Link memories explicitly |
Example: Unified Search
Search across STM and LTM with the CLI:
cortexgraph-search "typescript preferences" --tags preferences --limit 5 --verbose
Example: Reinforce (Touch) Memory
Boost a memory's recency/use count to slow decay:
{
"memory_id": "mem-123",
"boost_strength": true
}
Sample response:
{
"success": true,
"memory_id": "mem-123",
"old_score": 0.41,
"new_score": 0.78,
"use_count": 5,
"strength": 1.1
}
Example: Promote Memory
Suggest and promote high-value memories to the Obsidian vault.
Auto-detect (dry run):
{
"auto_detect": true,
"dry_run": true
}
Promote a specific memory:
{
"memory_id": "mem-123",
"dry_run": false,
"target": "obsidian"
}
As an MCP tool (request body):
{
"query": "typescript preferences",
"tags": ["preferences"],
"limit": 5,
"verbose": true
}
CortexGraph MCP 질문
CortexGraph MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add mnemex -- uvx mnemex를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
CortexGraph MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
CortexGraph MCP는 어떤 도구를 제공하나요?
13개 도구를 제공합니다. 예: save_memory, search_memory, search_unified, touch_memory, observe_memory_usage.
CortexGraph를 프로덕션 환경에서 사용할 수 있나요?
아니요, CortexGraph는 이론적 프레임워크를 검증하기 위한 연구용 결과물이자 개념 증명(PoC) 모델입니다. 상용 제품이 아니며 안정성을 보장하지 않습니다.
데이터는 어떻게 저장되고 보호되나요?
모든 데이터는 로컬 머신에 저장됩니다. 단기 메모리는 JSONL 파일 또는 SQLite를 사용하며, 장기 메모리는 Markdown 파일을 사용합니다. 클라우드 서비스나 추적 기능은 포함되어 있지 않습니다.