# 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](milestones/01-temporal-versioning.md) | Track how knowledge evolves over time | High |
| 2 | [Auto-Capture System](milestones/02-auto-capture.md) | Automatically capture Claude conversations | High |
| 3 | [Context Injection](milestones/03-context-injection.md) | Inject relevant memories at session start | High |
| 4 | [Codebase Indexing](milestones/04-codebase-indexing.md) | Scan and index project structure | High |
| 5 | [Daily Journal](milestones/05-daily-journal.md) | Quick capture and daily notes | Medium |
| 6 | [URL & Content Ingestion](milestones/06-content-ingestion.md) | Ingest URLs, PDFs, documents | Medium |
| 7 | [Graph Visualization](milestones/07-graph-visualization.md) | Export interactive HTML/SVG graphs | Medium |
| 8 | [Import/Export](milestones/08-import-export.md) | Obsidian, Markdown, JSON-LD support | Medium |
| 9 | [Multi-Graph Support](milestones/09-multi-graph.md) | Separate graphs per project | Medium |
| 10 | [Smart Retrieval](milestones/10-smart-retrieval.md) | Context-aware, git-integrated search | Medium |
| 11 | [TUI Dashboard](milestones/11-tui-dashboard.md) | Interactive terminal interface | Low |
| 12 | [Browser Extension](milestones/12-browser-extension.md) | Save from any webpage | Low |
| 13 | [Shell Completions](milestones/13-shell-completions.md) | 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](../CLAUDE.md) for contribution guidelines.