codecortex-ai 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +48 -58
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # CodeCortex
2
2
 
3
- > Persistent, AI-powered codebase knowledge layer. You shouldn't have to restructure your codebase for AI — CodeCortex gives AI the understanding automatically.
3
+ > Persistent codebase knowledge layer for AI agents. Your AI shouldn't re-learn your codebase every session.
4
4
 
5
5
  ## The Problem
6
6
 
7
- Every AI coding session starts from scratch. When context compacts or a new session begins, the AI must re-scan the entire codebase — same files, same tokens, same time. It's like hiring a new developer every session who has to re-learn your entire codebase before writing a single line.
7
+ 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.
8
8
 
9
9
  **The data backs this up:**
10
10
  - AI agents increase defect risk by 30% on unfamiliar code ([CodeScene + Lund University, 2025](https://codescene.com/hubfs/whitepapers/AI-Coding-Assistants-and-Code-Quality.pdf))
@@ -13,15 +13,15 @@ Every AI coding session starts from scratch. When context compacts or a new sess
13
13
 
14
14
  ## The Solution
15
15
 
16
- CodeCortex pre-digests codebases into layered, structured knowledge files and serves them to any AI agent via MCP. Instead of re-understanding your codebase every session, the AI starts with knowledge.
16
+ 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.
17
17
 
18
- **Hybrid extraction:** tree-sitter native N-API for precise structure (symbols, imports, calls across 27 languages) + host LLM for rich semantics (what modules do, why they're built that way). Zero extra API keys. Language-agnostic from day 1.
18
+ **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.
19
19
 
20
20
  ## Quick Start
21
21
 
22
22
  ```bash
23
23
  # Install
24
- npm install -g codecortex
24
+ npm install -g codecortex-ai
25
25
 
26
26
  # Initialize knowledge for your project
27
27
  cd /path/to/your-project
@@ -50,30 +50,22 @@ Add to your MCP config:
50
50
  }
51
51
  ```
52
52
 
53
- ## Architecture
53
+ ## What Gets Generated
54
+
55
+ All knowledge lives in `.codecortex/` as flat files in your repo:
54
56
 
55
57
  ```
56
- ANY AI AGENT (Claude Code, Cursor, Codex, Windsurf, Zed)
57
- │
58
- MCP Protocol (stdio)
59
- │
60
- ┌──────▼──────────────────────────────────────────────┐
61
- │ CODECORTEX MCP SERVER (14 tools) │
62
- │ READ (9): overview │ module │ briefing │ search │ │
63
- │ decisions │ graph │ lookup_symbol │ │
64
- │ change_coupling │ hotspots │
65
- │ WRITE (5): analyze_module │ save_analysis │ │
66
- │ record_decision │ update_patterns │ │
67
- │ report_feedback │
68
- └──────┬──────────────────────────────────────────────┘
69
- │ reads/writes
70
- ┌──────▼──────────────────────────────────────────────┐
71
- │ .codecortex/ (flat files in repo) │
72
- │ HOT: cortex.yaml │ constitution.md │ overview.md │
73
- │ graph.json │ symbols.json │ temporal.json │
74
- │ WARM: modules/*.md │
75
- │ COLD: decisions/*.md │ sessions/*.md │ patterns.md │
76
- └──────────────────────────────────────────────────────┘
58
+ .codecortex/
59
+ cortex.yaml # project manifest
60
+ constitution.md # project overview for agents
61
+ overview.md # module map + entry points
62
+ graph.json # dependency graph (imports, calls, modules)
63
+ symbols.json # full symbol index (functions, classes, types...)
64
+ temporal.json # git coupling, hotspots, bug history
65
+ modules/*.md # per-module deep analysis
66
+ decisions/*.md # architectural decision records
67
+ sessions/*.md # session change logs
68
+ patterns.md # coding patterns and conventions
77
69
  ```
78
70
 
79
71
  ## Six Knowledge Layers
@@ -81,35 +73,35 @@ ANY AI AGENT (Claude Code, Cursor, Codex, Windsurf, Zed)
81
73
  | Layer | What | File |
82
74
  |-------|------|------|
83
75
  | 1. Structural | Modules, deps, symbols, entry points | `graph.json` + `symbols.json` |
84
- | 2. Semantic | What each module DOES, data flow, gotchas | `modules/*.md` |
85
- | 3. Temporal | Git behavioral fingerprint — coupling, hotspots, bug history | `temporal.json` |
86
- | 4. Decisions | WHY things are built this way | `decisions/*.md` |
87
- | 5. Patterns | HOW code is written here | `patterns.md` |
88
- | 6. Sessions | What CHANGED between sessions | `sessions/*.md` |
76
+ | 2. Semantic | What each module does, data flow, gotchas | `modules/*.md` |
77
+ | 3. Temporal | Git behavioral fingerprint - coupling, hotspots, bug history | `temporal.json` |
78
+ | 4. Decisions | Why things are built this way | `decisions/*.md` |
79
+ | 5. Patterns | How code is written here | `patterns.md` |
80
+ | 6. Sessions | What changed between sessions | `sessions/*.md` |
89
81
 
90
- ### The Temporal Layer — Our Killer Differentiator
82
+ ### The Temporal Layer
91
83
 
92
- 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.
84
+ 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.
93
85
 
94
86
  Example from a real codebase:
95
- - `routes.ts` ↔ `worker.ts` co-changed 9/12 commits (75%) — **zero imports between them**
87
+ - `routes.ts` and `worker.ts` co-changed in 9/12 commits (75%) with **zero imports between them**
96
88
  - Without this knowledge, an AI editing one file would produce a bug 75% of the time
97
89
 
98
- ## MCP Tools
90
+ ## MCP Tools (14)
99
91
 
100
92
  ### Read Tools (9)
101
93
 
102
- | Tool | Description | Tier |
103
- |------|-------------|------|
104
- | `get_project_overview` | Constitution + overview + graph summary | HOT |
105
- | `get_module_context` | Module doc by name, includes temporal signals | WARM |
106
- | `get_session_briefing` | Changes since last session | COLD |
107
- | `search_knowledge` | Keyword search across all knowledge | COLD |
108
- | `get_decision_history` | Decision records filtered by topic | COLD |
109
- | `get_dependency_graph` | Import/export graph, filterable | HOT |
110
- | `lookup_symbol` | Symbol by name/file/kind | HOT |
111
- | `get_change_coupling` | "What files must I also edit if I touch X?" | HOT |
112
- | `get_hotspots` | Files ranked by risk (churn × coupling) | HOT |
94
+ | Tool | Description |
95
+ |------|-------------|
96
+ | `get_project_overview` | Constitution + overview + graph summary |
97
+ | `get_module_context` | Module doc by name, includes temporal signals |
98
+ | `get_session_briefing` | Changes since last session |
99
+ | `search_knowledge` | Keyword search across all knowledge |
100
+ | `get_decision_history` | Decision records filtered by topic |
101
+ | `get_dependency_graph` | Import/export graph, filterable |
102
+ | `lookup_symbol` | Symbol by name/file/kind |
103
+ | `get_change_coupling` | What files must I also edit if I touch X? |
104
+ | `get_hotspots` | Files ranked by risk (churn x coupling) |
113
105
 
114
106
  ### Write Tools (5)
115
107
 
@@ -130,24 +122,22 @@ Example from a real codebase:
130
122
  | `codecortex update` | Re-extract changed files, update affected modules |
131
123
  | `codecortex status` | Show knowledge freshness, stale modules, symbol counts |
132
124
 
133
- ## Progressive Disclosure
125
+ ## Token Efficiency
134
126
 
135
127
  CodeCortex uses a three-tier memory model to minimize token usage:
136
128
 
137
129
  ```
138
- Session start (HOT only): ~4,300 tokens ← full codebase understanding
139
- Working on a module (+WARM): ~5,000 tokens ← deep module knowledge
140
- Need coding patterns (+COLD): ~5,900 tokens ← every pattern + gotcha
130
+ Session start (HOT only): ~4,300 tokens
131
+ Working on a module (+WARM): ~5,000 tokens
132
+ Need coding patterns (+COLD): ~5,900 tokens
141
133
 
142
- vs. raw scan of entire codebase: ~37,800 tokens ← and still might miss things
134
+ vs. raw scan of entire codebase: ~37,800 tokens
143
135
  ```
144
136
 
145
- **Result: 85-90% token reduction, 80-85% fewer tool calls, 7-10x efficiency multiplier.**
137
+ 85-90% token reduction. 7-10x efficiency gain.
146
138
 
147
139
  ## Supported Languages (27)
148
140
 
149
- Native tree-sitter grammars for:
150
-
151
141
  | Category | Languages |
152
142
  |----------|-----------|
153
143
  | Web | TypeScript, TSX, JavaScript |
@@ -163,9 +153,9 @@ Native tree-sitter grammars for:
163
153
 
164
154
  - TypeScript ESM, Node.js 20+
165
155
  - `tree-sitter` (native N-API) + 27 language grammar packages
166
- - `@modelcontextprotocol/sdk` — MCP server
167
- - `commander` — CLI
168
- - `simple-git` — git integration
156
+ - `@modelcontextprotocol/sdk` - MCP server
157
+ - `commander` - CLI
158
+ - `simple-git` - git integration
169
159
  - `yaml`, `zod`, `glob`
170
160
 
171
161
  ## License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codecortex-ai",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Persistent, AI-powered codebase knowledge layer. Pre-digests codebases into structured knowledge and serves to AI agents via MCP.",
5
5
  "type": "module",
6
6
  "bin": {