Cortex

Private local memory for your AI tools.
Install once. Your tools stop starting from scratch.

     

Download  ·   Connect your tools  ·   What's new  ·   Roadmap

           

---

🔒 Private by default: localhost only, data never leaves your machine
🔗 One memory, every tool: HTTP and MCP, same brain, no per-tool silos
📊 Prove it works: token savings, recall quality, and Monte Carlo projections

---

❌ Without Cortex Session 1  →  explain preferences Session 2  →  explain them again Session 3  →  and again, new tool Session 14  →  still explaining ~15,000 tokens wasted

✅ With Cortex Session 1  →  store once Session 2  →  boot, already knows Session 3  →  boot, already knows Session 14  →  boot, still knows ~300 tokens per boot (97% less)

---

           

POST /store Save decisions, lessons, preferences. Conflict detection is automatic.

GET /recall Hybrid keyword + semantic search. In-process ONNX embeddings, no external service.

GET /boot Compiled identity + delta capsule. ~300 tokens served instead of ~15,000 raw.

---

Memory tools are easy to pitch and hard to trust. Cortex starts to matter when the savings stop looking theoretical.

📊 Analytics Savings, compression, and activity heatmaps	📈 Monte Carlo 30-day projection with confidence bands
🤖 Agents Live sessions, inbox, deduped by identity	🎛️ Overview Memory counts, health, and navigation

---

Measured against a 20-query ground-truth dataset on every release via the cortex-http-base adapter. A fully helper-free cortex-http-pure adapter is targeted for v0.6.0 to establish the canonical core baseline.

	v0.4.1	v0.5.0	Δ
Precision	55.2%	87.5%	📈 +32.3%
MRR	69.2%	95.0%	📈 +25.8%
Top-1 hit	90.0%	90.0%	—
Avg query tokens	n/a	48.4	—

_{Raw v0.5.0 JSON
Note: cortex-http-base ("raw") adapter retains partial adapter-layer helpers and is deprecated for new quality claims. The helper-free cortex-http-pure adapter is targeted for v0.6.0 as the canonical measurement floor -- planned v0.6.0+ recall-quality claims are measured through it, enforced by 5 CI purity gates. See benchmarking/README.md. Reranking production promotion remains targeted for v0.6.0 after validation; query expansion (HyDE) targeted for v0.7.0.}

---

349 commits since v0.4.1. Full details in CHANGELOG.md.

Retrieval

• Reciprocal rank fusion: query-adaptive keyword/semantic weighting
• Crystal family recall: collapsed members cut token cost, preserve context
• Synonym-expanded keywords across all retrieval paths
• FTS tokenizer upgrade and BM25 tuning
• Entity-alignment boost, co-occurrence expansion

Reliability

• Schema migration framework with upgrade regression tests
• DB integrity gate, rolling backups, crash-safe WAL
• Storage pressure governor with event-pressure controls
• Persistent savings rollups for long-window analytics
• DB footprint: 720 MB → 386 MB in a real install

Agent intelligence

• Feedback telemetry: record outcomes, track reliability over time
• Recall explainability: see why results ranked the way they did
• Conflict detection: AGREES / CONTRADICTS / REFINES / UNRELATED
• Client permissions: read / write / admin gates per agent

Security

• Localhost exempt from auth-failure lockout
• Non-loopback binds require TLS
• API key masking on non-interactive stdout
• Remote targets need explicit token (no silent auto-load)
• Team-mode destructive ops require admin + rated auth

---

Cortex tracks active agent sessions when clients identify themselves through cortex_boot or GET /boot?agent=NAME.

Multi-agent, one brain Each boot call registers a session. Control Center shows active sessions, deduplicated by agent identity. Read-path tools (recall, peek, unfold) reattach to existing sessions. No duplicates. Session descriptions preserved across reconnects and daemon restarts. What one agent stores, every other agent can recall. Claude Code, Codex, Cursor, and custom scripts can all be connected simultaneously. Each tracks its own session while sharing the same memory.

---

Tool	Connection	Setup
Claude Code	MCP (plugin) or desktop app	Plugin: claude plugin install cortex@cortex-marketplace
Codex	MCP	codex mcp add cortex -- cortex.exe mcp --agent codex
Cursor	MCP	Point MCP server at cortex mcp --agent cursor
Factory Droid	MCP	cortex mcp --agent droid
Aider	CLI / HTTP	cortex boot --agent aider
Custom tools	HTTP	Three endpoints: /boot, /recall, /store
Local LLMs	HTTP / MCP	Same protocol, any runtime

Full setup guide: Info/connecting.md

---

Desktop app (Control Center)
Download from the release page. The Control Center manages daemon lifecycle for you.

Platform	Desktop installer	Daemon archive
Windows	.exe (NSIS installer)	.zip
macOS	.dmg	.tar.gz
Linux	.AppImage / .deb	.tar.gz

From source

git clone https://github.com/AdityaVG13/cortex.git
cd cortex/daemon-rs
cargo build --release

Claude Code plugin

claude plugin marketplace add AdityaVG13/cortex
claude plugin install cortex@cortex-marketplace

The plugin handles daemon startup, health checks, and MCP bridging automatically.

---

Cortex enforces a single-daemon invariant: only one daemon process runs at a time.

Mode	How it works
Desktop app	Control Center owns the daemon. Restart and monitor from the app.
CLI	cortex serve starts the daemon. Exits cleanly if one is already running.
Plugin	cortex plugin ensure-daemon attaches to an existing daemon or starts one.

Default bind: 127.0.0.1:7437. Non-loopback binds require TLS. Auth token at ~/.cortex/cortex.token.
If using the Control Center, manage the daemon from there. Do not run a second cortex serve alongside it.

---

After installing, verify everything works:

# Start the daemon (skip if using Control Center)
cortex serve &

# Health check (no auth required)
curl http://localhost:7437/health

# Boot test
TOKEN=$(cat ~/.cortex/cortex.token)
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Cortex-Request: true" \
     "http://localhost:7437/boot?agent=smoke-test"

# Store and recall round-trip
curl -X POST http://localhost:7437/store \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Cortex-Request: true" \
     -d '{"decision": "smoke test", "context": "verifying install"}'

curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Cortex-Request: true" \
     "http://localhost:7437/recall?q=smoke+test"

Development build verification

# Daemon unit tests
cargo test --manifest-path daemon-rs/Cargo.toml

# Desktop test suite
npm --prefix desktop/cortex-control-center test

# Lifecycle smoke test
npm --prefix desktop/cortex-control-center run verify:lifecycle:dev

# Security audit
npm audit --omit=dev --audit-level=high
cargo audit

---

Document	Covers
Connecting	Setup, MCP, HTTP, auth, troubleshooting
MCP Tools	All 28 MCP tool definitions and parameters
Research	Papers, inspirations, adaptation notes
Roadmap	What shipped, what's planned, and why
Security	Threat model, auth rules, vulnerability reporting
Team mode	Shared-server setup for engineering teams
Contributing	Development setup and PR guidelines

CLI reference

Command	Description
cortex serve	Start the daemon
cortex --help	Full command reference
cortex doctor	Run diagnostics
cortex paths --json	Show file and port paths
cortex plugin ensure-daemon	Ensure daemon health (plugin mode)
cortex plugin mcp	MCP stdio bridge to HTTP API
cortex setup --team	Initialize team mode and generate API keys
cortex export	Export data (json or sql)
cortex import	Import from a previous export
cortex admin rollback --session-id <id>	Soft-delete a session's memory writes (dry-run default; --apply to persist)

---

Cortex defaults to localhost-only access with bearer-token auth.
Full threat model, auth rules, and vulnerability reporting: Info/security-rules.md

---

💾 How much disk space does Cortex use?

The daemon binary is ~30 MB. The SQLite database grows with usage. A real install with 286 memories and 493 decisions uses ~386 MB after compaction. The ONNX embedding model (~50 MB) downloads on first run.

🤖 Can multiple agents write to Cortex at the same time?

Yes. SQLite WAL mode handles concurrent reads and serialized writes. Each agent maintains its own session while sharing the same memory. Conflict detection handles contradictions automatically.

🔒 Does Cortex send any data externally?

No. In solo mode, Cortex runs entirely on localhost. No telemetry, no phone-home, no cloud sync. Team mode sends data only to the configured team server over your network.

🔄 What happens if the daemon crashes mid-session?

The MCP proxy detects daemon death and restarts automatically (bounded to 3 attempts with backoff). SQLite WAL mode ensures no data corruption. Sessions survive transient crashes.

🧹 How do I reset Cortex to a clean state?

Delete ~/.cortex/cortex.db and restart the daemon. A new empty database and auth token are generated. Settings and model files are preserved.

---

Built by

---

☕ Support Cortex  ·   Research  ·   Connecting  ·   Security  ·   Contributing  ·   Code of Conduct  ·   Changelog  ·   MIT License