🧠 Cortex — Proactive Memory Agent for AI Coding Assistants

Obsidian-backed knowledge graph with semantic search, entity extraction, and cross-session memory. 11 MCP tools. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible editor.

---

What It Does

You: "How does the memory system handle forgetting?"
Cortex: 💡 This reminds me of your previous work on:
       1. decisions/memory-architecture-choice — Ebbinghaus decay with 14-day half-life
       2. daily/2026-06-19 — You designed the three-tier memory architecture
       3. moc/system-architecture — Full system diagram

• Semantic search — Find concepts across languages (EN query → CN content)
• Knowledge graph — 928 entities, 106K relationships, auto-extracted from your notes
• Proactive context — memory_monitor watches conversation topics, surfaces relevant memories
• Gap analysis — Compare your learning goals against actual knowledge coverage
• Cross-session — Every session loads your memory index + recent daily logs automatically

Architecture

MCP Client (Claude Code / Cursor / Windsurf)
       │  stdio JSON-RPC
       ▼
┌─────────────────────────────────┐
│  Cortex MCP Server (TypeScript) │
│  11 tools + 1 resource          │
│  ┌───────────────────────────┐  │
│  │ SQLite (sql.js)           │  │  ← Knowledge graph (8 tables)
│  │ LanceDB                   │  │  ← Vector embeddings (384-dim)
│  │ ONNX (all-MiniLM-L6-v2)   │  │  ← Local, zero API cost
│  └───────────────────────────┘  │
└──────────────┬──────────────────┘
               │ reads & indexes
               ▼
┌─────────────────────────────────┐
│  Obsidian Vault (source of truth)│
│  daily/  decisions/  moc/       │
│  学习计划/  ...                  │
└─────────────────────────────────┘

Quick Start

# 1. Install
cd Cortex/mcp-server
npm install --ignore-scripts
npx tsc

# 2. Configure (Claude Code)
# Copy the MCP config to your global Claude Code settings:
# ~/.claude/.mcp.json

# 3. Use
# Start a Claude Code session. The MCP server starts automatically.
# Say: "memory_ingest" to index your vault
# Say: "search for architecture decisions" to find memories

MCP Tools

Tool	Description
memory_search	Hybrid keyword + vector semantic search
memory_ingest	Scan vault, extract entities, build index
memory_status	System health report
memory_entity_extract	Extract typed entities from text
memory_graph_query	Query the knowledge graph (multi-hop)
memory_auto_link	Suggest [[wikilinks]] between notes
memory_monitor	Process conversation, return proactive context
memory_conflict_resolve	Detect contradictions with existing memories
memory_gap_analysis	Analyze knowledge gaps vs learning goals
memory_consolidate	Apply decay, find archive candidates
memory_session_end	Generate daily note (portable Stop hook)

Editor Support

Editor	Setup
Claude Code	~/.claude/.mcp.json (global) or .mcp.json (project)
Cursor	Copy editors/cursor.mcp.json → .cursor/mcp.json
Windsurf	Copy editors/windsurf.mcp.json
Cline / VS Code	Copy editors/cline.mcp.json

Project Structure

Cortex/
├── mcp-server/               ← TypeScript MCP server (32 source files)
│   ├── src/
│   │   ├── tools/            ← 11 MCP tools
│   │   ├── graph/            ← Knowledge graph + decay + gap detection
│   │   ├── ingest/           ← Vault scanner, chunker, entity extractor
│   │   ├── embeddings/       ← ONNX pipeline (all-MiniLM-L6-v2)
│   │   ├── db/               ← SQLite + LanceDB
│   │   └── resources/        ← MCP resource endpoints
│   ├── editors/              ← Config templates for other editors
│   └── tests/
├── src/
│   ├── hooks/                ← Bash hooks (SessionStart, Stop, etc.)
│   ├── lib/                  ← Bash utilities
│   └── templates/            ← Vault file templates
├── skills/                   ← Claude Code skills
├── commands/                 ← Slash commands
├── docs/                     ← Architecture docs
└── tests/                    ← Hook tests

License

MIT — see LICENSE