Add development plan with 13 milestone specifications
- docs/plan.md: Master roadmap with phases and priorities - docs/milestones/01-13: Detailed specs for each feature - Updated CLAUDE.md with plan references and build commands Milestones cover: - Phase 1: Temporal versioning, auto-capture, context injection, codebase indexing - Phase 2: Daily journal, content ingestion, graph visualization, import/export - Phase 3: Multi-graph, smart retrieval, TUI dashboard, browser extension, shell completions
This commit is contained in:
109
docs/plan.md
Normal file
109
docs/plan.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user