Cognitive Codebase Matrix (CCM)

English | Turkce

🧠 The Codebase Graph Backbone for AI Agents

Bridge the gap between your codebase and your AI editor. CCM transforms static source code into a dynamic, queryable Knowledge Graph, enabling AI agents to navigate, understand, and reason about your project with surgical precision.

Current release: v0.3.13. An external benchmark on real repositories (serde, flask, express) with 35 hand-verified golden tasks, honest Recall@K/MRR/latency metrics, and hybrid scoring at 82.9% vs 80.0% semantic-only — plus the v0.3.12 durable background semantic upgrade and the 180/180 offline semantic gate.

---

Why CCM?

Modern AI coding assistants (Claude, Cursor, Windsurf) are powerful but suffer from blindness:

CCM turns raw code into a queryable graph so agents answer connected logic questions instead of guessing from similar words.

The “Agent-First” Difference

Unlike tools that dump raw code, CCM injects AI-Optimized Context:

• Logical Reasoning - Explains why code was retrieved
• Relational Edges - Maps how files talk to each other
• Confidence Scores - Shows certainty in results

CCM vs. Alternatives

Many AI-context tools stop at semantic search: they embed files and return chunks that merely look similar. CCM layers a real dependency graph on top.

The one-line pitch: “Don’t just search your codebase - map it.” CCM gives your agent the dependency graph, not just similar-looking text. That turns questions like “what breaks if I change this?” from guesses into queryable facts.

---

Key Features

🧠 Connected Intelligence (Graph Navigator)

• Two-Pass Indexing - Links function definitions to call sites
• Incremental Refresh - Re-indexes only added, modified, renamed, or deleted files after the first run
• Deep Traversal - Ask “Who calls this?” and get accurate answers

⚡ High-Performance Core

• Rust-Powered - Blazing fast indexing and queries
• Batch Embedding - Thousands of lines in seconds
• LanceDB - Millisecond-latency vector storage
• Tree-sitter - Robust AST for Rust, Python, TypeScript, JavaScript, Go, Java, Kotlin, C#, C, C++, Ruby, PHP, and Swift

🔒 Production Hardening

• Binary Checksums - Release artifacts include checksums.txt for integrity
• MCP Allowlist - Restrict project access with CCM_ALLOWED_ROOTS
• Safe Defaults - UTF-8-safe chunking, configurable timeouts, retries, and file-size limits

🔌 Universal Compatibility (MCP)

• Plug & Play - Installer configures Codex, Cursor, Claude Desktop, and Antigravity
• Explicit Indexing - Missing indexes fail fast and point to index_project
• Zero-Config - Auto-detects project root

---

Installation

⚡ Automatic (Recommended)

# 1. Configure MCP for your AI editor
npx @senoldogann/context-manager install

# 2. Index your project
npx @senoldogann/context-manager index --path .

First-Run Verification

After installation, verify the happy path with a clean smoke test:

# Check that the CLI responds
npx @senoldogann/context-manager query --text "src/main.rs:1"

# Start the MCP server directly
npx @senoldogann/context-manager mcp

Expected outcomes:

• The wrapper downloads the correct binary for your OS and architecture
• index creates data/ccm_db inside the project
• mcp starts without JSON-RPC parse errors and waits on stdio

Editor Compatibility

If your editor is not auto-detected, use the manual MCP config printed by the installer.

🤖 Agent Skill

CCM ships a SKILL.md in both the source repository and npm tarball. AI agents can load it to understand all 9 MCP tools, stable node IDs, recommended flow, and common pitfalls.

Copy it into your agent’s skill directory and it becomes a first-class tool reference:

# Install to your local agents skill directory
cp SKILL.md ~/.agents/skills/context-manager/SKILL.md

🔧 Manual Build (Rust)

# If local source builds fail, install protoc first.
# macOS: brew install protobuf

git clone https://github.com/senoldogann/LLM-Context-Manager.git
cd LLM-Context-Manager
cargo build --release

# Binary location: target/release/ccm-cli

No Rust toolchain? Use the Docker option in GETTING_STARTED.md.

Manual npm publication (maintainers)

The npm manifest is intentionally inside npm/, not the repository root:

cd npm
npm test
npm pack --dry-run
npm publish --access public --provenance

---

Configuration

Create ~/.ccm/.env (or start from the repository’s .env.example):

# Option A: Local (Recommended - Privacy)
EMBEDDING_PROVIDER=ollama
EMBEDDING_HOST=http://127.0.0.1:11434
EMBEDDING_MODEL=mxbai-embed-large
# No API key is required for local Ollama.

# Option B: Cloud (OpenAI)
EMBEDDING_PROVIDER=openai
EMBEDDING_API_KEY=sk-your-key
EMBEDDING_MODEL=text-embedding-3-small

# Networking & Limits
EMBEDDING_TIMEOUT_SECS=30
CCM_MAX_FILE_BYTES=2097152

# MCP Security (strict allowlist is ON by default)
CCM_ALLOWED_ROOTS=/Users/you/projects:/Users/you/sandbox
CCM_REQUIRE_ALLOWED_ROOTS=1

# MCP Runtime
CCM_MCP_ENGINE_CACHE_SIZE=8
CCM_MCP_DEBUG=0

# Optional: disable embeddings entirely (semantic search disabled)
CCM_DISABLE_EMBEDDER=0

# Optional: embed data files (md/json/yaml) into vector search
CCM_EMBED_DATA_FILES=0

# npm wrapper security (0 = enforce checksum, 1 = bypass)
CCM_ALLOW_UNVERIFIED_BINARIES=0

# Optional download tuning (milliseconds / attempts)
CCM_DOWNLOAD_TIMEOUT_MS=120000
CCM_DOWNLOAD_ATTEMPTS=3

Advanced overrides:

• CCM_PROJECT_ROOT pins the default project root used by the npm wrapper and MCP fallback engine.
• CCM_DB_PATH overrides the default MCP vector DB location.
• .env.example contains the full advanced tuning surface for chunking, batch size, hybrid ranking weights, and compatibility aliases such as OPENAI_API_KEY, CCM_SKIP_CHECKSUM, CCM_MCP_REQUIRE_ALLOWED_ROOTS, CCM_EMBED_DATA, and EMBEDDING_DISABLED.
• Hybrid weight tuning details live in docs/hybrid-ranking.md.

Note: Requires Ollama running (ollama serve) with model pulled (ollama pull mxbai-embed-large). Security: MCP enforces a strict allowlist by default — only directories under CCM_ALLOWED_ROOTS (falling back to CCM_PROJECT_ROOT) can be indexed or read. Set CCM_REQUIRE_ALLOWED_ROOTS=0 only if you explicitly want the relaxed mode; even then, access stays confined to the startup project root.

---

Usage

CLI Commands

# Index a project
ccm-cli index --path .

# Search semantically
ccm-cli query --text "authentication logic"

# Cursor prediction (file:line format)
ccm-cli query --text "src/main.rs:50"

# Watch mode - auto-reindex
ccm-cli index --path . --watch

# Diagnose installer, allowlist, and index compatibility
ccm-cli doctor --path .

# Evaluate retrieval quality
ccm-cli eval --tasks eval/golden_tasks.v3.ccm.json

MCP Tools

Incremental indexing behavior

The first index builds the complete index. Later index_project or index --watch runs compare the filesystem manifest and update only changed or newly created files while removing deleted-file nodes. The vector database is not rebuilt when nothing changed. Cross-file reference edges are refreshed from the in-memory semantic graph so callers remain accurate after a symbol changes. Retrieval tools fail fast when an index is missing or being updated; call index_project explicitly instead of making a search request wait for a hidden rebuild.

For large repositories, MCP index_project returns before the client’s timeout and continues in the background. Call the tool again to poll until it returns the final indexing statistics.

For fast first-response workflows, call index_project or index_now with mode: "quick". This scans and parses sources, builds the navigation graph, and returns nearly immediately without waiting on the embedding provider. A background task then fills the semantic vectors from the same graph; until that completes, search_code serves graph-ranked results instead of failing. Use mode: "upgrade" (or index_now with "upgrade") to repair or complete a graph-only index that was created while the embedding backend was unavailable, without re-parsing source files.

Full rebuilds are prepared in a staging generation. A scan, parse, embedding or vector write failure leaves the previous graph, manifest and vector table in place. File fingerprints include content, so same-size edits with preserved timestamps are still detected.

---

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ AI Agent    │────▶│ MCP Server  │────▶│ Core Engine │
│ (Claude)    │◀────│ (ccm-mcp)   │◀────│ (Rust)      │
└─────────────┘     └─────────────┘     └─────────────┘
                                                  │
                    ┌────────────────────────────┼────────────────────────────┐
                    ▼                            ▼                            ▼
             ┌─────────────┐            ┌─────────────┐            ┌─────────────┐
             │ Code Graph  │            │  Vector DB  │            │  Parser     │
             │ (Petgraph)  │            │  (LanceDB)  │            │(Tree-sitter)│
             └─────────────┘            └─────────────┘            └─────────────┘

---

Supported Languages

---

Evaluation

CCM includes a golden task evaluation framework:

# Run evaluation
ccm-cli eval --tasks eval/golden_tasks.v3.ccm.json

# Compare structural vs hybrid scoring
ccm-cli eval --tasks eval/golden_tasks.v3.ccm.json --compare

If the evaluation index is missing, CCM bootstraps it automatically before scoring. Semantic search_code tasks still require a configured embedder.

Latest Recorded Results: The offline synthetic semantic gate passes 180/180 tasks (100%) as of v0.3.12, and CI now enforces it with --min-pass-rate 100 (no regression); structural-only gate is 50/50 100%. See eval/report.semantic.json.

External benchmark (v0.3.13): 35 hand-verified golden tasks on real repos (serde, flask, express) with real Ollama embeddings. Hybrid scoring passes 82.9% (29/35) vs 80.0% (28/35) semantic-only; get_context/read_graph are 11/11. Full numbers, failure ledger and reproduction steps: benchmarks/README.md.

---

Release Reliability

CCM release builds are designed to be reproducible and install-safe:

• GitHub Releases publish platform binaries and checksums.txt
• The npm wrapper verifies downloaded binaries before first use
• MCP transport now enforces request size limits and redacts sensitive debug payloads
• The release workflow builds Linux, macOS, and Windows artifacts before attaching release assets
• npm publication is a separate manual step from npm/ after the GitHub Release assets are attached
• The README quick-start now matches the same smoke path we use for first-install checks

For local source builds, cargo build --release still requires protoc to be installed on your machine.

---

Troubleshooting

“No context found”

1. Run ccm-cli index --path . first
2. If you override it, check CCM_PROJECT_ROOT matches the indexed directory
3. Ensure Ollama is running

Slow indexing

• First run downloads embedding model (~1.5GB)
• Subsequent runs are fast (incremental)

“Checksum manifest not found” / “Checksum mismatch”

1. Ensure the GitHub Release includes checksums.txt
2. Re-run the install once
3. As a last resort, set CCM_ALLOW_UNVERIFIED_BINARIES=1 to bypass verification

“Project path is not allowed”

• Strict allowlist mode is enabled by default
• Set CCM_ALLOWED_ROOTS to include the project root
• Only if you really need it, disable strict mode with CCM_REQUIRE_ALLOWED_ROOTS=0 (access still stays within the startup project root)

Large/binary files are skipped

• Increase CCM_MAX_FILE_BYTES if you need larger text files indexed

Data files not showing in search

• By default, data files (.md, .json, .yaml) are indexed but not embedded.
• Enable CCM_EMBED_DATA_FILES=1 to include them in semantic search.

---

Resources

• NPM Package: @senoldogann/context-manager
• Turkish README: README.tr.md
• Getting Started: GETTING_STARTED.md
• Environment Example: .env.example
• Hybrid Ranking Notes: docs/hybrid-ranking.md
• Contributing: CONTRIBUTING.md

---

Star History

---

License

MIT License - Open source and free to use.