# CodeContext

Semantic memory system for Claude Code sessions. Captures learnings, stores them with vector embeddings, and provides retrieval via semantic similarity search.

## Features

- **Automatic Memory Capture**: Hooks capture learnings from coding sessions
- **Semantic Search**: Find relevant past experiences using natural language
- **Project Summaries**: AI-generated summaries injected into new sessions
- **Conflict Detection**: Identifies contradictory or outdated memories
- **Memory Consolidation**: Merges related memories to reduce redundancy

## Quick Start

### Installation

```bash
# Install the package
pip install codecontext

# Initialize for all projects (global)
codecontext init --global

# Or initialize for current project only
codecontext init --project
```

### Interactive Setup

```bash
codecontext init
```

This will prompt you to choose between:
1. **Global** - Active for ALL projects (~/.claude/)
2. **Project** - Active only for THIS project (./.claude/)

### Basic Usage

```bash
# Search your memories
codecontext query "authentication flow"

# Add a new memory
codecontext add --type bugfix --title "Fixed timezone" --fact "Use make_naive=True"

# Quick note (auto-classifies)
codecontext note "Always use utcnow() for storage"

# View project summary
codecontext summary

# List known gotchas
codecontext gotchas

# Check server health
codecontext health
```

## Installation Modes

| Mode | Hooks Location | Data Location | Use Case |
|------|----------------|---------------|----------|
| **Global** | `~/.claude/hooks/codecontext/` | `~/.codecontext/` | Single user, all projects |
| **Project** | `./.claude/hooks/codecontext/` | `./.codecontext/` | Per-project isolation |

## Commands

| Command | Description |
|---------|-------------|
| `init` | Set up hooks and skills |
| `uninstall` | Remove hooks (preserves data by default) |
| `server` | Start the CodeContext server |
| `query <text>` | Semantic search |
| `add` | Add a memory with type, title, fact |
| `note <text>` | Quick capture with auto-classification |
| `resolve <desc>` | Mark a priority as completed |
| `files <path>` | Find memories by file |
| `summary` | View project summary |
| `summary-generate` | Generate/regenerate summary |
| `recent` | Show recent memories |
| `gotchas` | List known pitfalls |
| `stats` | Project statistics |
| `projects` | List all projects |
| `health` | Server health check |

## Memory Types

| Type | Description |
|------|-------------|
| `bugfix` | Bug fixes and solutions |
| `feature` | New functionality |
| `discovery` | How things work |
| `decision` | Architecture choices |
| `refactor` | Code restructuring |
| `optimization` | Performance improvements |
| `gotcha` | Pitfalls to avoid |
| `resolution` | Completed priorities |

## Server

The CodeContext server runs locally and provides:
- REST API for memory operations
- Web UI for browsing memories
- Background tasks for consolidation

```bash
# Start server manually
codecontext server

# With custom port
codecontext server --port 9000

# Development mode with auto-reload
codecontext server --reload
```

The server starts automatically when hooks fire or CLI commands run.

## Architecture

```
~/.codecontext/
├── projects/
│   └── {encoded-project-path}/
│       ├── vector_db/       # LanceDB storage
│       ├── summary.json     # Current summary
│       └── sessions/        # Session logs
├── config.json              # Server config
└── .codecontext_mode        # Installation marker
```

## Uninstalling

```bash
# Remove hooks, keep your data
codecontext uninstall --global

# Remove everything including memories
codecontext uninstall --global --remove-data
```

## Migration from agentic-coder

If you were using the development version from agentic-coder:

1. Install the pip package: `pip install codecontext`
2. Run init: `codecontext init --global`
3. Your existing data in `~/.codecontext/` is automatically preserved

## Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# With GPU support
pip install -e ".[full]"
```

## Requirements

- Python 3.10+
- Claude Code CLI (for hooks)
- ~200MB disk space (FastEmbed model)

## License

MIT License - see [LICENSE](LICENSE)
