Cortex Index — Local-First AI Workspace Manager

Persistent knowledge graph for your codebase. Cortex Index converts source code into a queryable graph with symbol resolution, call tracking, and token-optimized AI context building — all local, no cloud, no vector DB.

⚡ Key Features

20 MCP Tools — Full Model Context Protocol (MCP v1.0) over stdio JSON-RPC 2.0
🧠 Brain System — Persistent .cortex/brain.md stores project purpose, rules, and knowledge. Created on cortex init, queryable via cortex_brain_get/update/append MCP tools. AI agents learn once, remember forever.
Search Layer — Three search tools: recursive knowledge base search, line-level grep across workspace files, and glob pattern matching for file discovery.
Skills Management — Install, uninstall, list, search, and update reusable AI skill conventions templates. Both workspace-scoped and global.
Task Tracking — Create, update, complete, list, show, and delete tracked tasks in .cortex/tasks/.
Codebase Documentation — Auto-generated architecture overview (codebase.md) with metadata that stays in sync via cortex update.
Project-Local — No global database. Each project owns .cortex/ next to it. cortex init creates it. cortex clean resets it.
Embedded Storage — Pebble LSM tree embedded KV store at .cortex/data/.

🏗️ Architecture

 ┌──────────────┐
 │ AI Agent │
 │ (Claude/etc) │
 └──────┬───────┘
 │ MCP (Stdio)
 ┌─────────────────────────┐
 │ Cortex MCP Server │
 │ 20 tools · JSON-RPC 2.0 │
 └─────────────────────────┘
 │
 ┌─────────────────┼─────────────────┐
 │ │ │
 ┌────▼────┐ ┌────▼─────┐ ┌──────▼──────┐
 │ Brain │ │ Search │ │ Skills & │
 │ (3 tools)│ │ (3 tools) │ │ Tasks │
 └─────────┘ └──────────┘ │ (7 tools) │
 └──────────────┘
 │
 ┌─────────────────────┼─────────────────────┐
 │ │
 ┌─────▼─────┐ ┌──────▼──────┐
 │ Codebase │ │ Project │
 │ (3 tools) │ │ Metadata │
 └───────────┘ └──────────────┘

🚀 Getting Started

# Install
git clone https://github.com/Haslab-dev/CortexIndex.git
cd CortexIndex && make && make install
# Create a project
cd ~/my-project
cortex init # creates .cortex/ + project.json + brain.md + codebase.md + full index
cortex update # refresh project metadata and codebase.md
# Quick MCP test
cortex mcp call cortex_brain_get '{}'

🧠 Brain System — Persistent Agent Knowledge

The brain file (.cortex/brain.md) records your project's purpose, rules, and explanations. Created automatically on cortex init. AI agents read it to understand context without codebase exploration.

# Read brain
cortex brain
# Add knowledge (append)
cortex brain add "Uses Pebble KV storage"
# Append as "Learned"
cortex brain append "Providers self-register via init() calling Register()"
# Add a rule
cortex brain rule add "All APIs must have timeout handling"
# Add a permission
cortex brain permission add "can access database credentials"
# Set an instruction
cortex brain instruction set "Always check .cortex/brain.md before modifying code"
# Search brain content
cortex brain search "Pebble"
# Via MCP (agent-friendly)
cortex mcp call cortex_brain_append '{"line":"Uses Pebble KV storage"}'

The brain persists between agent sessions — knowledge learned once is retained.

📊 Performance Benchmarks

Tested on cortex-index (self-project):

Operation	Time	Notes
Brain get	<1ms	Read brain.md content
Brain append	<1ms	append-only write
Grep workspace	<1ms	Recursive text search
Glob pattern	<1ms	File path matching
Skill CRUD	<1ms	install/uninstall/list/search/update
Task CRUD	<1ms	create/update/complete/list/show/delete
Codebase init	<1ms	Generate architecture overview
Codebase update	<1ms	Refresh metadata

🔌 20 MCP Tools Reference

🧠 Brain (3 tools)

Tool	Description	Example
`cortex_brain_get`	Read brain.md (purpose/rules)	`{}`
`cortex_brain_update`	Replace brain.md content	`{"content":"## Purpose\n..."}`
`cortex_brain_append`	Append line as "Learned"	`{"line":"Uses Pebble storage"}`

🔍 Search (3 tools)

Tool	Description	Example
`cortex_search`	Search knowledge base and codebase files recursively	`{"query":"MCP"}`
`cortex_grep`	Search for target text within workspace files	`{"query":"cortex"}`
`cortex_glob`	Match file paths in workspace using glob pattern	`{"pattern":"*/.go"}`

🎯 Skills (5 tools)

Tool	Description	Example
`cortex_skill_install`	Install a coding skill conventions template	`{"name":"refactor"}`
`cortex_skill_uninstall`	Uninstall a coding skill conventions template	`{"name":"refactor"}`
`cortex_skill_list`	List all global and workspace skills	`{}`
`cortex_skill_search`	Search for skills by query text	`{"query":"refactor"}`
`cortex_skill_update`	Update or install coding skill content	`{"name":"refactor"}`

✅ Tasks (6 tools)

Tool	Description	Example
`cortex_task_create`	Create a task tracking document	`{"name":"test","goal":"Test"}`
`cortex_task_update`	Update active task status	`{"name":"test","status":"in_progress"}`
`cortex_task_complete`	Mark a task tracking document completed	`{"name":"test"}`
`cortex_task_list`	List all registered workspace tasks	`{}`
`cortex_task_show`	Show detailed task instructions	`{"name":"test"}`
`cortex_task_delete`	Delete/remove task document from workspace	`{"name":"test"}`

📁 Codebase (3 tools)

Tool	Description	Example
`cortex_codebase_init`	Initialize codebase.md architecture overview	`{}`
`cortex_codebase_update`	Update codebase.md metadata recursively	`{}`
`cortex_codebase_get`	Get the content of the codebase.md architecture overview file	`{}`

🔌 MCP Client Configuration

Claude Desktop / Antigravity / Cursor / Kilo AI

{
 "mcpServers": {
 "cortex-index": {
 "command": "cortex",
 "args": ["mcp", "stdio"]
 }
 }
}

MCP is stdio-only. No HTTP transport. The server runs per-session and exits when the parent closes stdin.

🧪 Tutorial: AI Agent Working with Cortex

Step 1 — Initialize the project

cortex init
# → ✓ Initialized Cortex 2.0 project 'my-project'

Step 2 — Explore the brain

cortex brain
# → Shows brain.md content
cortex mcp call cortex_brain_get '{}'
# → Returns brain.md content as JSON-RPC response

Step 3 — Search the codebase

cortex search "MCP"
# → Returns matching lines from knowledge base and codebase files
cortex grep "cortex"
# → Returns matching lines in workspace files
cortex glob "**/*.go"
# → Returns matching file paths

Step 4 — Manage tasks

cortex task create refactor-router "Refactor API router" "Use handler pattern"
cortex task list
cortex task update refactor-router in_progress
cortex task complete refactor-router
cortex task delete refactor-router

Step 5 — Manage skills

cortex skill install refactor
cortex skill list
cortex skill search refactor
cortex skill update refactor "Updated content here"
cortex skill uninstall refactor

Step 6 — Persistent learning via brain

cortex brain append "Uses Pebble KV storage at .cortex/data/"
cortex brain rule add "All APIs must have timeout handling"
cortex brain permission add "can access database credentials"
# Via MCP (agent-friendly)
cortex mcp call cortex_brain_append '{"line":"Uses Pebble KV storage"}'

🧪 Testing & Verification

MCP Tool Verification (2026年07月31日)

All 20 MCP tools were tested against this project using the cortex MCP interface:

#	Tool	Test Input	Result
1	`cortex_search`	`{"query":"MCP"}`	✅ Returns matching results
2	`cortex_grep`	`{"query":"cortex"}`	✅ Returns matching lines in workspace files
3	`cortex_glob`	`{"pattern":"*/.go"}`	✅ Returns matching file paths
4	`cortex_brain_get`	`{}`	✅ Returns brain.md content
5	`cortex_brain_append`	`{"line":"Test line"}`	✅ Appended "Learned" entry
6	`cortex_brain_update`	`{"content":"Updated"}`	✅ Replaced brain content
7	`cortex_skill_install`	`{"name":"refactor"}`	✅ Installed skill
8	`cortex_skill_uninstall`	`{"name":"refactor"}`	✅ Uninstalled skill
9	`cortex_skill_list`	`{}`	✅ Lists installed skills
10	`cortex_skill_search`	`{"query":"refactor"}`	✅ Returns matching skills
11	`cortex_skill_update`	`{"name":"refactor"}`	✅ Updated skill
12	`cortex_task_create`	`{"name":"test","goal":"Test"}`	✅ Task created
13	`cortex_task_list`	`{}`	✅ Lists tasks
14	`cortex_task_show`	`{"name":"test"}`	✅ Shows task details
15	`cortex_task_update`	`{"name":"test","status":"in_progress"}`	✅ Updated
16	`cortex_task_complete`	`{"name":"test"}`	✅ Completed
17	`cortex_task_delete`	`{"name":"test"}`	✅ Deleted
18	`cortex_codebase_init`	`{}`	✅ Initialized codebase.md
19	`cortex_codebase_update`	`{}`	✅ Updated codebase.md metadata
20	`cortex_codebase_get`	`{}`	✅ Returns codebase.md content

Category Summary

Category	Tools	Count	Status
Brain	brain_get, brain_update, brain_append	3	✅ All passing
Search	search, grep, glob	3	✅ All passing
Skills	skill_install, skill_uninstall, skill_list, skill_search, skill_update	5	✅ All passing
Tasks	task_create, task_update, task_complete, task_list, task_show, task_delete	6	✅ All passing
Codebase	codebase_init, codebase_update, codebase_get	3	✅ All passing
Total	20	✅ All passing

🛠️ CLI Reference

cortex init Initialize .cortex directory, project.json, brain.md, codebase.md
cortex update Update project metadata and codebase.md
cortex doctor Check system environment and project health
cortex codebase [init|update|show|append]
 Manage codebase.md architecture files
cortex brain [add|show|search|rule add|permission add|instruction set|prune]
 Manage persistent append-only workspace brain logs
cortex task [create|update|continue|complete|list|show|delete]
 Manage workspace tasks in .cortex/tasks/
cortex skill [install|uninstall|list|search|update]
 Manage workspace and global AI skills
cortex search <query> Orchestrate searches across knowledge and files
cortex grep <query> Grep text in workspace
cortex glob <pattern> Match file paths in workspace
cortex mcp stdio Start MCP stdio server
cortex mcp call <toolName> [jsonArgs]
 Execute MCP tool directly

Name		Name	Last commit message	Last commit date
.cortex		.cortex
bin		bin
cmd/cortex		cmd/cortex
pkg		pkg
Makefile		Makefile
README.md		README.md
VERSION		VERSION
go.mod		go.mod

Uh oh!

Latest commit

History

Folders and files

Repository files navigation