ccengram

CCEngram

Semantic code search and persistent memory for Claude Code.

CCEngram lets Claude Code search your codebase by meaning, not just keywords. Ask questions like "how does authentication work?" or "where are errors handled?" and get relevant results even when the exact terms don't appear in the code. Optionally, enable automatic memory extraction (uses Haiku on your Claude Code subscription) to have Claude remember your preferences, decisions, and project-specific patterns across sessions.

[!WARNING] This project was primarily vibecoded. It is not a reflection of my skills and definitely not Rust best practices. I made it to solve a specific problem (working in large monorepos with Claude), so likely won't accept a bunch of tangential features.

The intention is that this plugin is as set-and-forget as possible. Once you run an initial indexing for a project, CCEngram's file watcher keeps the index up-to-date automatically as you code. The daemon will shut itself down after 5 minutes of inactivity, and automatically restart and reconcile index changes as requests come in.

Features

• Hybrid Code Search - Find code by meaning (vector) and keywords (FTS), fused via Reciprocal Rank Fusion
• Cross-Encoder Reranking - Reranker refines results after initial retrieval (enabled by default via llama.cpp)
• Persistent Memory - Preferences, decisions, and patterns remembered across sessions (opt-in per project)
• File Watching - Index updates automatically as you code
• Per-Project Isolation - Each project has its own index and memories
• Interactive TUI - Browse and manage code, documents, and memories

Installation

Prerequisites

CCEngram uses llama.cpp for embedding and reranking by default - no API keys required. Models are downloaded automatically from HuggingFace on first use.

For better speed and performance, cloud providers are recommended:

• OpenRouter (cloud, recommended) - Set OPENROUTER_API_KEY
• DeepInfra (cloud, recommended) - Set DEEPINFRA_API_KEY
• Ollama (local) - Run embeddings locally

Install

curl -fsSL https://raw.githubusercontent.com/JoeyEamigh/ccengram/main/scripts/install.sh | bash

Or install from source:

cargo install --git https://github.com/JoeyEamigh/ccengram --bin ccengram

For in-process llama.cpp with GPU acceleration (recommended for local inference):

cargo install --git https://github.com/JoeyEamigh/ccengram --bin ccengram --features llama-cpp,vulkan
# GPU options: vulkan (recommended), cuda, metal

Claude Code Plugin

Install from the Claude Code plugin marketplace:

/plugin marketplace add JoeyEamigh/ccengram
/plugin install ccengram

Quick Start

1. Initialize Your Project

Navigate to your project and create a project-specific config:

cd /your/project
ccengram config init # creates the project config
ccengram agent # installs the SemExplore agent

This creates .claude/ccengram.toml. The default minimal preset is recommended for most users. You can choose a different preset:

• minimal - 2 tools: explore, context (recommended)
• standard - 11 tools: search + memory management + code maintenance
• full - 34 tools: everything

ccengram config init --preset standard  # If you want the agent to be able to modify the database

2. Index Your Codebase

ccengram index

This scans your project and creates semantic embeddings. By default, CCEngram uses llama.cpp for embedding and reranking - models are downloaded automatically on first use, no configuration needed.

[!TIP] For better speed and performance, use a cloud embedding provider. OpenRouter and DeepInfra are recommended. See Embedding Providers below.

3. File Watching (Automatic)

The file watcher automatically starts after indexing and whenever an indexed project is accessed. Your index stays up-to-date as you edit files.

Ignoring Files

CCEngram respects .gitignore patterns. For additional exclusions specific to CCEngram, create a .ccengramignore file in your project root using the same syntax:

# Example .ccengramignore
generated/
*.auto.ts
vendor/

To manually control the watcher:

ccengram watch --status    # Check watcher status
ccengram watch --stop      # Stop the watcher
ccengram watch             # Manually start (if stopped)

The watcher performs a startup scan when launched to detect any files that changed while it wasn't running.

4. Start Using

With Claude Code: MCP tools are automatically available. Claude uses explore and context to search your codebase and memories.

CLAUDE.md Recommendations

To help Claude Code make the best use of CCEngram, add something like this to your project's CLAUDE.md:

## Claude

## Semantic Code Search (CCEngram)