# Cortex Development Guidelines

## Development Plan

See [docs/plan.md](docs/plan.md) for the full roadmap and milestone breakdown.

### Current Phase: Core Memory System
- [Milestone 1: Temporal Versioning](docs/milestones/01-temporal-versioning.md)
- [Milestone 2: Auto-Capture System](docs/milestones/02-auto-capture.md)
- [Milestone 3: Context Injection](docs/milestones/03-context-injection.md)
- [Milestone 4: Codebase Indexing](docs/milestones/04-codebase-indexing.md)

---

## Project Memory Guidelines

### Before Making Changes
- **Always query memory** before modifying code or making architectural decisions: use `memory_query` to search for relevant context.
- Use `memory_show` to check existing context on a specific topic before acting.
- Check for existing decisions, gotchas, and component info that may affect your changes.

### After Making Changes
- **Store new decisions** as memory nodes (kind: `decision`) when architectural choices are made.
- **Store gotchas** as memory nodes (kind: `memory`) when you discover non-obvious behavior.
- **Store component info** (kind: `component`) when creating or significantly modifying a module.
- Tag nodes appropriately for future retrieval.

## Memory Tools (MCP)

| Tool | Description |
|------|-------------|
| `memory_query` | Search memory by text (hybrid BM25 + vector) |
| `memory_show` | Show a node by ID or prefix |
| `memory_list` | List nodes filtered by kind/status/tags |
| `memory_children` | List children of a node |
| `memory_add` | Add a new memory node |
| `memory_link` | Create a relationship between nodes |
| `memory_split` | Break a large node into smaller children |
| `memory_merge` | Merge multiple nodes into one |
| `memory_dedupe` | Find similar/duplicate nodes |
| `memory_prune` | Clean up stale nodes or orphans |
| `memory_stats` | Get graph statistics |
| `memory_summary` | Get hierarchical summary of the graph |
| `memory_prompt` | Execute natural language instruction |

## Build Commands

```bash
# Development
npm run build          # Compile TypeScript
npm run dev            # Watch mode

# Standalone Executables
npm run package:win    # Windows (cortex.exe + cortex-mcp.exe)
npm run package:linux  # Linux
npm run package:mac    # macOS

# Run
node dist/cli/index.js <command>  # Development
./build/cortex.exe <command>      # Standalone
```

## Git Preferences
- Do not add `Co-Authored-By` lines to commits.
- Keep commits focused on single milestones when possible.