---
name: codecontext
description: >-
  Semantic memory system storing learnings from past coding sessions.
  CAPABILITIES: Search memories by topic, find memories by file path, store bug fixes/decisions/discoveries, list known gotchas, view project summaries.
  USE WHEN: (1) Before implementing a feature - search for relevant context, (2) Before modifying a file - check for related memories, (3) When debugging - search for similar past bugs, (4) After fixing a bug or making a decision - store the learning, (5) User asks about project history or past decisions.
allowed-tools: Bash(python*cli.py*), Read, Glob
argument-hint: [query, command, or topic]
---

# CodeContext - Project Memory System

A semantic memory system that stores learnings from past coding sessions. Query it before implementing features, check for known gotchas, and store new discoveries for future sessions.

---

## Quick Start

```bash
# Search for relevant memories
python codecontext/cli.py query "authentication flow" --top-k 5 --json

# Check what files a memory relates to
python codecontext/cli.py files "utils/auth.py" --json

# Add a new memory
python codecontext/cli.py add --type bugfix --title "Fixed X" --fact "Details..." --json

# View project summary
python codecontext/cli.py summary --json

# List known gotchas
python codecontext/cli.py gotchas --json
```

---

## Current Project Context

**Project Stats:**
!`python codecontext/cli.py stats --json 2>/dev/null || echo '{"status": "server not running"}'`

**Recent Learnings (last 5):**
!`python codecontext/cli.py recent --limit 5 --json 2>/dev/null || echo '[]'`

**Known Gotchas:**
!`python codecontext/cli.py gotchas --json 2>/dev/null || echo '[]'`

---

## Core Workflow

### Before Implementing

1. **Search relevant memories** - Find past learnings about the topic
2. **Check related files** - See if there are memories about files you'll modify
3. **Review gotchas** - Check for known pitfalls

### After Completing Work

1. **Store the learning** - Add what you discovered or decided
2. **Tag with files** - Link to relevant files for future searches

---

## Commands Reference

### Global Options (all commands)

| Flag | Description |
|------|-------------|
| `-p, --project TEXT` | Override auto-detected project |
| `-u, --url TEXT` | Override server URL |
| `--no-auto-start` | Disable automatic server startup |
| `--json` | Output as parseable JSON |

---

### `query` - Semantic search

```bash
python codecontext/cli.py query "topic" --top-k 5 --json
python codecontext/cli.py query "bug" --type bugfix --json
```

| Flag | Description |
|------|-------------|
| `QUERY_TEXT` | Search text (required) |
| `-k, --top-k INTEGER` | Number of results (1-20) |
| `-t, --type TYPE` | Filter: bugfix, feature, discovery, decision, refactor, optimization, gotcha, resolution, all |
| `--min-score FLOAT` | Minimum similarity (0-1) |

---

### `files` - Find memories by file path

```bash
python codecontext/cli.py files "path/to/file.py" --json
python codecontext/cli.py files "auth" --match-mode fuzzy --json
```

| Flag | Description |
|------|-------------|
| `FILE_PATHS...` | One or more file paths (required) |
| `--match-mode` | exact, contains, or fuzzy |

---

### `add` - Add a new memory

```bash
python codecontext/cli.py add \
  --type bugfix \
  --title "Short searchable title" \
  --fact "Detailed description of what you learned" \
  --files "file1.py,file2.py" \
  --json
```

| Flag | Description |
|------|-------------|
| `-t, --type TYPE` | Memory type (required) |
| `--title TEXT` | Short searchable title (required) |
| `--fact TEXT` | The learning details (required) |
| `--files TEXT` | Comma-separated file paths |
| `--confidence` | high, medium, or low |

---

### `resolve` - Mark priority as resolved

```bash
python codecontext/cli.py resolve "Implemented progressive summary generation"
python codecontext/cli.py resolve "Fixed timestamp standardization"
```

| Flag | Description |
|------|-------------|
| `DESCRIPTION` | What was resolved (required) |

Creates a `resolution` type memory with auto-generated title and fact.

---

### `recent` - Show recent memories

```bash
python codecontext/cli.py recent --limit 10 --json
```

| Flag | Description |
|------|-------------|
| `-n, --limit INTEGER` | Number of memories to show |

---

### `gotchas` - List known gotchas

```bash
python codecontext/cli.py gotchas --json
```

---

### `stats` - Project statistics

```bash
python codecontext/cli.py stats --json
```

---

### `projects` - List all projects

```bash
python codecontext/cli.py projects --json
```

---

### `health` - Check server health

```bash
python codecontext/cli.py health --json
```

---

### `summary` - Get project summary

```bash
python codecontext/cli.py summary --json
python codecontext/cli.py summary --include-timeline --include-stats --json
```

| Flag | Description |
|------|-------------|
| `--include-timeline` | Include recent activity |
| `--include-stats` | Include memory statistics |

### Summary Management

```bash
# View current project summary
python codecontext/cli.py summary --json

# Generate/regenerate project summary (incremental)
python codecontext/cli.py summary-generate --json

# Force full regeneration (fixed-size chunks)
python codecontext/cli.py summary-generate --force-full --json

# Progressive regeneration (time-based chunking)
# Best for fixing stale "Next Priority" sections
python codecontext/cli.py summary-generate --progressive --json
```

#### Summary Generation Modes

| Mode | Flag | Description |
|------|------|-------------|
| Incremental | (default) | Only process new memories since last summary |
| Force Full | `--force-full` | Replay all memories in fixed 50-memory chunks |
| Progressive | `--progressive` | Time-based chunking that keeps sessions together (best for resolving stale priorities) |

The **progressive mode** processes memories chronologically with intelligent time-based chunking:
- Groups memories from the same work session together (~8 hour gaps = new session)
- Targets ~30 memories per chunk but flexes to maintain coherence
- Naturally handles priority resolution as Claude "sees" history unfold

### Mark Priorities as Resolved

```bash
# Explicitly mark a priority as completed
python codecontext/cli.py resolve "Implemented progressive summary generation"
python codecontext/cli.py resolve "Fixed timestamp standardization"

# Then regenerate summary to reflect the change
python codecontext/cli.py summary-generate --progressive --json
```

Use `resolve` when priorities were completed outside normal memory capture (decisions, discussions) or to explicitly clean up stale priorities.

### Bulk Import (Bootstrap from History)

Import memories from existing Claude Code session transcripts. Useful for bootstrapping CodeContext on projects with existing history.

```bash
# Preview what would be imported (dry run)
python codecontext/tools/bulk_import.py --project "C:\Users\Sam\my-project" --dry-run

# Import all sessions
python codecontext/tools/bulk_import.py --project "..." --yes

# Import only last 7 days of sessions
python codecontext/tools/bulk_import.py --project "..." --days 7 --yes

# Limit to 10 most recent sessions
python codecontext/tools/bulk_import.py --project "..." --limit 10 --yes

# Process max 20 chunks with 2s delay between
python codecontext/tools/bulk_import.py --project "..." --max-chunks 20 --delay 2 --yes

# Process oldest sessions first (bootstrap from history start)
python codecontext/tools/bulk_import.py --project "..." --oldest-first --yes
```

#### Bulk Import Flags

| Flag | Description |
|------|-------------|
| `--project`, `-p` | Path to the project directory (required) |
| `--days`, `-d` | Only import sessions from the last N days |
| `--limit`, `-l` | Limit to N most recent sessions |
| `--max-chunks`, `-m` | Maximum total chunks to process |
| `--delay` | Delay in seconds between chunks (default: 0.5) |
| `--oldest-first` | Process oldest sessions first |
| `--dry-run` | Preview without importing |
| `--yes`, `-y` | Auto-confirm (skip prompt) |

---

## Memory Types

| Type | Description | When to Use |
|------|-------------|-------------|
| `bugfix` | Bug fixes and solutions | Fixed an error, crash, or unexpected behavior |
| `feature` | New feature implementations | Added new functionality |
| `discovery` | Codebase discoveries | Found how something works, hidden behavior |
| `decision` | Architecture decisions | Made a design choice with rationale |
| `refactor` | Code refactoring notes | Restructured or cleaned up code |
| `optimization` | Performance improvements | Made something faster or more efficient |
| `gotcha` | Pitfalls and warnings | Found a trap others should avoid |
| `resolution` | Priority completions | Marked a priority/issue as resolved |

---

## Examples

### Pre-Implementation Check

Before working on authentication:

```bash
# Search for auth-related memories
python codecontext/cli.py query "authentication" --top-k 5 --json

# Check if there are memories about auth files
python codecontext/cli.py files "auth" --match-mode fuzzy --json

# Review any gotchas
python codecontext/cli.py gotchas --json
```

### Storing a Bug Fix

After fixing a timezone bug:

```bash
python codecontext/cli.py add \
  --type bugfix \
  --title "Fixed timezone comparison in datetime utils" \
  --fact "Use make_naive=True to strip timezone info before comparing datetime objects. Without this, comparisons fail silently when one datetime is naive and one is aware." \
  --files "utils/datetime.py,tests/test_datetime.py" \
  --json
```

### Storing a Discovery

Found something interesting:

```bash
python codecontext/cli.py add \
  --type discovery \
  --title "LanceDB L2 distance thresholds" \
  --fact "Lower L2 distance means more similar. Range 0.3-0.65 works best for technical content." \
  --files "store.py" \
  --json
```

### Storing an Architecture Decision

Made a design choice:

```bash
python codecontext/cli.py add \
  --type decision \
  --title "Using mixins for memory store separation of concerns" \
  --fact "Split MemoryStore into core class plus ArchiveMixin, ConflictMixin, SummaryMixin, ConsolidationMixin to keep each under 800 lines and improve testability." \
  --files "store.py,mixins/" \
  --json
```

### Marking a Priority as Resolved

When a priority from the summary is completed:

```bash
python codecontext/cli.py resolve "Implemented progressive summary generation"
```

---

## When to Use Memory

| Situation | Action | Command |
|-----------|--------|---------|
| Before implementing a feature | Search for context | `query "feature-topic"` |
| Before modifying a file | Check file memories | `files "path/to/file.py"` |
| When debugging an issue | Search for similar bugs | `query "error description" --type bugfix` |
| Encounter unexpected behavior | Check gotchas | `gotchas` |
| After fixing a bug | Store the fix | `add --type bugfix ...` |
| After making a decision | Document rationale | `add --type decision ...` |
| Found something interesting | Store discovery | `add --type discovery ...` |
| Found a pitfall | Warn future devs | `add --type gotcha ...` |
| Completed a priority | Mark resolved | `resolve "description"` |

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Server not running" | Run `python codecontext/server.py` in a separate terminal |
| No results found | Try broader search terms or different keywords |
| Wrong project detected | Use `--project PATH` to specify the correct project |
| Slow first query | Normal - embedding model loads on first request (~30s on Windows) |

---

## Your Task

$ARGUMENTS

**Remember**:
- Always use `--json` flag for parseable output
- Check memory BEFORE implementing solutions
- Store significant learnings AFTER completing work
- Run commands from the project root directory
