CodeCortex

Persistent codebase knowledge layer for AI agents. Your AI shouldn't re-learn your codebase every session.

Website · npm · GitHub

The Problem

Every AI coding session starts from scratch. When context compacts or a new session begins, the AI re-scans the entire codebase. Same files, same tokens, same wasted time. It's like hiring a new developer every session who has to re-learn everything before writing a single line.

The data backs this up:

• AI agents increase defect risk by 30% on unfamiliar code (CodeScene + Lund University, 2025)
• Code churn grew 2.5x in the AI era (GitClear, 211M lines analyzed)
• Nobody combines structural + semantic + temporal + decision knowledge in one portable tool

The Solution

CodeCortex pre-digests codebases into layered knowledge files and serves them to any AI agent via MCP. Instead of re-understanding your codebase every session, the AI starts with knowledge.

Hybrid extraction: tree-sitter native N-API for structure (symbols, imports, calls across 27 languages) + host LLM for semantics (what modules do, why they're built that way). Zero extra API keys.

Quick Start

# Install
npm install -g codecortex-ai

# Initialize knowledge for your project
cd /path/to/your-project
codecortex init

# Start MCP server (for AI agent access)
codecortex serve

# Check knowledge freshness
codecortex status

Connect to Claude Code

Add to your MCP config:

{
  "mcpServers": {
    "codecortex": {
      "command": "codecortex",
      "args": ["serve"],
      "cwd": "/path/to/your-project"
    }
  }
}

What Gets Generated

All knowledge lives in .codecortex/ as flat files in your repo:

.codecortex/
  cortex.yaml          # project manifest
  constitution.md      # project overview for agents
  overview.md          # module map + entry points
  graph.json           # dependency graph (imports, calls, modules)
  symbols.json         # full symbol index (functions, classes, types...)
  temporal.json        # git coupling, hotspots, bug history
  modules/*.md         # per-module deep analysis
  decisions/*.md       # architectural decision records
  sessions/*.md        # session change logs
  patterns.md          # coding patterns and conventions

Six Knowledge Layers

Layer	What	File
1. Structural	Modules, deps, symbols, entry points	graph.json + symbols.json
2. Semantic	What each module does, data flow, gotchas	modules/*.md
3. Temporal	Git behavioral fingerprint - coupling, hotspots, bug history	temporal.json
4. Decisions	Why things are built this way	decisions/*.md
5. Patterns	How code is written here	patterns.md
6. Sessions	What changed between sessions	sessions/*.md

The Temporal Layer

This is the killer differentiator. The temporal layer tells agents "if you touch file X, you MUST also touch file Y" even when there's no import between them. This comes from git co-change analysis, not static code analysis.

Example from a real codebase:

• routes.ts and worker.ts co-changed in 9/12 commits (75%) with zero imports between them
• Without this knowledge, an AI editing one file would produce a bug 75% of the time

MCP Tools (14)

Read Tools (9)

Tool	Description
get_project_overview	Constitution + overview + graph summary
get_module_context	Module doc by name, includes temporal signals
get_session_briefing	Changes since last session
search_knowledge	Keyword search across all knowledge
get_decision_history	Decision records filtered by topic
get_dependency_graph	Import/export graph, filterable
lookup_symbol	Symbol by name/file/kind
get_change_coupling	What files must I also edit if I touch X?
get_hotspots	Files ranked by risk (churn x coupling)

Write Tools (5)

Tool	Description
analyze_module	Returns source files + structured prompt for LLM analysis
save_module_analysis	Persists LLM analysis to modules/*.md
record_decision	Saves architectural decision to decisions/*.md
update_patterns	Merges coding pattern into patterns.md
report_feedback	Agent reports incorrect knowledge for next analysis

CLI Commands

Command	Description
codecortex init	Discover project + extract symbols + analyze git history
codecortex serve	Start MCP server (stdio transport)
codecortex update	Re-extract changed files, update affected modules
codecortex status	Show knowledge freshness, stale modules, symbol counts

Token Efficiency

CodeCortex uses a three-tier memory model to minimize token usage:

Session start (HOT only):           ~4,300 tokens
Working on a module (+WARM):         ~5,000 tokens
Need coding patterns (+COLD):        ~5,900 tokens

vs. raw scan of entire codebase:    ~37,800 tokens

85-90% token reduction. 7-10x efficiency gain.

Supported Languages (27)

Category	Languages
Web	TypeScript, TSX, JavaScript
Systems	C, C++, Objective-C, Rust, Zig, Go
JVM	Java, Kotlin, Scala
.NET	C#
Mobile	Swift, Dart
Scripting	Python, Ruby, PHP, Lua, Bash, Elixir
Functional	OCaml, Elm, Emacs Lisp
Other	Solidity, Vue, CodeQL

Tech Stack

• TypeScript ESM, Node.js 20+
• tree-sitter (native N-API) + 27 language grammar packages
• @modelcontextprotocol/sdk - MCP server
• commander - CLI
• simple-git - git integration
• yaml, zod, glob

License

MIT