io.github.DanielBlomma/cortex
Local repo context for coding assistants with semantic search and graph relationships.
Ask AI about io.github.DanielBlomma/cortex
Powered by Claude · Grounded in docs
I know everything about io.github.DanielBlomma/cortex. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Cortex MCP
@danielblomma/cortex-mcp is a local, repo-scoped context platform for coding assistants.
It indexes your codebase into structured entities (files, rules, ADRs) and exposes that context over MCP (JSON-RPC over stdio).

Why Use Cortex
- Semantic search across code and documentation.
- Graph relationships between entities and architectural constraints.
- Local-first: your code and context stay on your machine.
- Incremental updates keep context fresh as the repo changes.
- Works with Claude Code/Desktop and Codex MCP clients.
Core Features
- Semantic search (files, rules, ADRs).
- Graph relationships between entities and constraints.
- Architectural rules and ADR context for implementation decisions.
Advanced Features (Experimental)
Cortex can extract function-level chunks and build call graphs in experimental builds:
context.find_callers- what calls this function?context.trace_calls- what does this function call?context.impact_analysis- what is impacted if this function changes?- Requires JavaScript/TypeScript codebase and semantic chunking/call graph indexing enabled.
These APIs are experimental and may not be exposed in every installation.
Chunking Strategy (Code)
When semantic chunking is enabled, large function/method chunks are split into overlap windows during ingest.
Defaults:
CORTEX_CHUNK_WINDOW_LINES=80CORTEX_CHUNK_OVERLAP_LINES=16CORTEX_CHUNK_SPLIT_MIN_LINES=120CORTEX_CHUNK_MAX_WINDOWS=8
Behavior:
- Chunks are split only when the chunk body exceeds the split threshold.
- Windows slide forward using configured overlap (
next_start = previous_end - overlap). - The last allowed window always stretches to the end of the chunk body.
- Window chunks inherit metadata (
status,source_of_truth) from their parent chunk. - Window chunks inherit parent graph edges for
CALLSandIMPORTSto keep traversal/ranking consistent.
Verification:
- Overlap and windowing regressions are covered in
tests/context-regressions.test.mjs.
Requirements
- Node.js 18+
- Git repository
- Optional for auto-connection:
claudeand/orcodexCLI inPATH
Install
npm i -g @danielblomma/cortex-mcp
Quick Start
From the repository you want to index:
cortex init --bootstrap
This will:
- scaffold
.context/,scripts/,mcp/,.githooks/, and docs files - build and prepare the local MCP server
- try to auto-register MCP connections for Claude/Codex (if installed)
- start background sync unless disabled
Disable watcher setup:
cortex init --bootstrap --no-watch
Check semantic search readiness:
cortex status
Look for semantic_search=embedding+lexical (ready) to confirm full semantic mode.
Verify MCP Connection
Claude:
claude mcp list
Codex:
codex mcp list
Claude Plugin Marketplace
Install via Claude Code plugin marketplace:
/plugin marketplace add DanielBlomma/cortex
/plugin install cortex@cortex-marketplace
/plugin enable cortex
Then initialize Cortex in your target repository:
cortex init --bootstrap
Manual MCP Configuration
If auto-registration is unavailable, configure MCP manually.
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"cortex": {
"command": "cortex",
"args": ["mcp"],
"env": {
"CORTEX_PROJECT_ROOT": "/absolute/path/to/your-project"
}
}
}
}
Codex (~/.config/codex/mcp-config.json):
{
"mcpServers": {
"cortex-myproject": {
"command": "cortex",
"args": ["mcp"],
"cwd": "/absolute/path/to/your-project"
}
}
}
MCP Tools
context.search
Ranked context search across indexed entities.
Input:
query(string, required)top_k(int, 1-20, default5)include_deprecated(bool, defaultfalse)include_content(bool, defaultfalse)
context.get_related
Fetch entity relationships from the graph.
Input:
entity_id(string, required)depth(int, 1-3, default1)include_edges(bool, defaulttrue)
context.get_rules
List indexed rules and optionally include inactive rules.
Input:
scope(string, optional)include_inactive(bool, defaultfalse)
context.reload
Reload the RyuGraph connection after updates/maintenance.
Input:
force(bool, defaulttrue)
Example Prompts
- "Find files that handle authentication."
- "Show related files for this ADR."
- "What active architectural rules apply to this API?"
Common Commands
cortex init [path] [--force] [--bootstrap] [--connect] [--no-connect] [--watch] [--no-watch]
cortex connect [path] [--skip-build]
cortex mcp
cortex bootstrap
cortex update
cortex status
cortex watch [start|stop|status|run|once] [--interval <sec>] [--debounce <sec>] [--mode <auto|event|poll>]
cortex note <title> [text]
cortex plan
cortex todo [text|list|done <id>|reopen <id>|remove <id>]
cortex help
Automated Release
This repository includes two GitHub Actions workflows:
-
Release Bump(.github/workflows/release-bump.yml)- Manual
workflow_dispatchfrommain - Bumps semver (
patch/minor/major) - Syncs release metadata files (
package.json,server.json, plugin manifests) - Runs tests
- Commits and tags
vX.Y.Z
- Manual
-
Release Publish(.github/workflows/release-publish.yml)- Triggers on tag push
v*.*.* - Verifies tag/version sync
- Runs root tests + MCP build/tests
- Publishes
@danielblomma/cortex-mcpto npm
- Triggers on tag push
Required GitHub secret:
NPM_TOKEN(npm automation token with publish rights for@danielblomma/cortex-mcp)
Limitations
- Requires repo initialization (
cortex init --bootstrap). - Each repository has its own local Cortex context instance.
- No cloud sync by design (privacy-first local storage).
Security and Privacy
- Cortex stores context data locally under
.context/. - No source code upload is required for core functionality.
Troubleshooting
mcp/dist/server.jsmissing: Runcortex bootstrap(or re-runcortex init --bootstrap).claudeorcodexnot found during init: Auto-registration is skipped; use manual config above.- MCP tools return stale context:
Run
cortex update, then reconnect MCP or callcontext.reloadfrom your MCP client.
Support
- Issues: https://github.com/DanielBlomma/cortex/issues
- Marketplace prep notes: docs/MCP_MARKETPLACE.md
License
MIT
