claude-codecontext 0.1.0

Semantic memory system for Claude Code sessions

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

# 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

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

# 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

# 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

# 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

# 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