# 🧠 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

```bash
# 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](LICENSE)