cortex/docs/plan.md

Cortex Development Plan

Vision

Transform Cortex from a CLI knowledge graph into a comprehensive AI memory system that automatically captures, organizes, and resurfaces knowledge — making Claude (and other AI agents) truly remember across sessions.

Guiding Principles

1. Local-first — All data stays on your machine (SQLite + Ollama)
2. Invisible capture — Memory happens automatically, not manually
3. Graph-native — Everything is nodes and edges, not flat documents
4. Interoperable — Import/export to standard formats
5. Standalone — Single executable, no runtime dependencies

---

Milestones Overview

#	Milestone	Description	Priority
1	Temporal Versioning	Track how knowledge evolves over time	High
2	Auto-Capture System	Automatically capture Claude conversations	High
3	Context Injection	Inject relevant memories at session start	High
4	Codebase Indexing	Scan and index project structure	High
5	Daily Journal	Quick capture and daily notes	Medium
6	URL & Content Ingestion	Ingest URLs, PDFs, documents	Medium
7	Graph Visualization	Export interactive HTML/SVG graphs	Medium
8	Import/Export	Obsidian, Markdown, JSON-LD support	Medium
9	Multi-Graph Support	Separate graphs per project	Medium
10	Smart Retrieval	Context-aware, git-integrated search	Medium
11	TUI Dashboard	Interactive terminal interface	Low
12	Browser Extension	Save from any webpage	Low
13	Shell Completions	Bash/Zsh/Fish/PowerShell autocomplete	Low

---

Phase 1: Core Memory System (Milestones 1-4)

Goal: Make Cortex a true "memory layer" for Claude Code

These milestones transform Cortex from a manual note-taking tool into an automatic memory system:

• Temporal Versioning — Know what you knew and when
• Auto-Capture — Every conversation becomes searchable memory
• Context Injection — Claude starts each session with relevant context
• Codebase Indexing — Understand project structure automatically

Phase 2: Knowledge Acquisition (Milestones 5-8)

Goal: Make it easy to get knowledge INTO the system

• Daily Journal — Quick thoughts, todos, daily capture
• Content Ingestion — URLs, PDFs, docs → memory nodes
• Graph Visualization — See and understand your knowledge
• Import/Export — Interop with Obsidian, other tools

Phase 3: Advanced Features (Milestones 9-13)

Goal: Power user features and polish

• Multi-Graph — Separate contexts per project
• Smart Retrieval — Git-aware, context-aware search
• TUI Dashboard — Beautiful terminal interface
• Browser Extension — Capture from anywhere
• Shell Completions — Developer experience polish

---

Success Metrics

• Claude can recall information from previous sessions without prompting
• New projects are automatically indexed and understood
• Daily workflow doesn't require manual memory management
• Knowledge survives across machines via export/import
• Sub-100ms query latency on 10k+ nodes

---

Technical Decisions

Decision	Choice	Rationale
Database	SQLite	Local-first, single file, portable
Embeddings	Ollama	Private, local, no API keys
Packaging	esbuild + pkg	Standalone exe, no Node.js
Graph storage	Adjacency list in SQL	Simple, fast for our scale
MCP transport	stdio	Standard, works everywhere

---

Dependencies & Risks

Risk	Mitigation
Ollama not installed	Graceful fallback to BM25-only search
Large codebases slow indexing	Incremental indexing, .gitignore respect
Claude Code API changes	Abstract MCP layer, version pin
SQLite concurrency	WAL mode, connection pooling

---

Getting Started

1. Read the milestone docs in order
2. Each milestone is independently shippable
3. PRs should target one milestone at a time
4. Update this plan as we learn

See CLAUDE.md for contribution guidelines.