@ai-cortex/daemon 0.1.0

package/LICENSE

@@ -0,0 +1,64 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Cortex
+Licensed Work:        Cortex Daemon 0.1.0
+                      The Licensed Work is (c) 2026 Cortex.
+Additional Use Grant: You may make use of the Licensed Work, provided that
+                      you may not use the Licensed Work for a Service that
+                      competes with the Licensed Work. A "Service" is a
+                      commercial offering that provides substantially the
+                      same functionality as the Licensed Work to third
+                      parties as a managed service, hosted solution, or
+                      distributed product.
+Change Date:          2030-03-21
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact the Licensor.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under the
+terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently
+in effect as described in this License, you must purchase a commercial license
+from the Licensor, its affiliated entities, or authorized resellers, or you must
+refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of
+the Licensed Work. If you receive the Licensed Work in original or modified form
+from a third party, the terms and conditions set forth in this License apply to
+your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates (provided that you may use a trademark or logo of Licensor as
+expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
+OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.

package/README.md

@@ -0,0 +1,217 @@
+# Cortex
+
+A transparent API proxy daemon that makes LLM coding agents smarter. Set one environment variable and Cortex sits between your coding agent and the LLM provider — observing conversations, fingerprinting tasks, injecting relevant knowledge from a local brain directory, and tracking multi-agent sessions in real time.
+
+## How It Works
+
+```
+Claude Code / Cursor / Aider
+        │
+        ▼
+   localhost:9090  ◄── Cortex daemon
+        │
+        │  1. Detect & classify agent (main, subagent, teammate)
+        │  2. Parse messages
+        │  3. Prune verbose tool outputs (day-1 value)
+        │  4. Fingerprint conversation (rules + semantic embedding)
+        │  5. Match against brain directory (RRF fusion)
+        │  6. Inject best match if confident
+        │
+        ▼
+  api.anthropic.com
+```
+
+Cortex never modifies responses — only request bodies. SSE streaming passes through raw and unmodified.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Run the interactive setup wizard
+npm run setup
+
+# Start the daemon
+npm run dev
+
+# In another terminal, point your agent at Cortex
+export ANTHROPIC_BASE_URL=http://localhost:9090
+
+# Use your agent normally — Cortex works transparently
+claude
+```
+
+## Day-1 Value
+
+With zero configuration and an empty brain, Cortex provides **always-on pruning** of verbose tool outputs. Tool results over 500 tokens are automatically summarized (keeping the first and last 50 tokens with a summary line), reducing context bloat on every request.
+
+## Brain Directory
+
+The brain is a collection of Markdown files with YAML frontmatter in `brain/entries/`. Each entry is a solution, pattern, or fix that Cortex can inject when it detects a matching situation.
+
+```yaml
+---
+id: node-esm-import
+title: "Node.js ESM import resolution"
+language: javascript
+error_types: [ERR_MODULE_NOT_FOUND, "Cannot find module"]
+tags: [debugging, imports, node, esm]
+---
+
+When you see ERR_MODULE_NOT_FOUND in an ESM project...
+```
+
+Cortex ships with 13 seed entries covering common issues (ESM imports, Python venvs, CORS, merge conflicts, etc.). Add your own by dropping `.md` files into `brain/entries/`.
+
+### Multi-Source Brain
+
+Brain entries can come from multiple sources beyond local files:
+- **local** — Markdown+YAML files from registered directories
+- **cheat.sh** — Community-driven cheat sheets (1 req/sec throttle)
+- **tldr** — Simplified man pages from GitHub
+- **devdocs** — DevDocs API adapter
+
+Manage sources with `cortex brain sources`.
+
+## Intelligence Pipeline
+
+1. **Fingerprinter** — Extracts features from the conversation: programming languages, error types, file types, conversation phase, and a 384-dim semantic embedding via BGE-small (local ONNX model).
+
+2. **Matcher** — Two retrieval channels fused via Reciprocal Rank Fusion:
+   - CH1: Weighted Jaccard similarity on rule features (language, error types, tags)
+   - CH2: Cosine similarity on semantic embeddings
+
+3. **Injector** — If the top match exceeds the confidence threshold (0.9), injects the brain entry content into the last user message wrapped in `<cortex_context>` tags. Max 16K chars (~4000 tokens).
+
+## Agent Tracking
+
+Cortex automatically detects and classifies agents passing through the proxy:
+
+- **Main sessions** — Full Claude Code sessions with CLAUDE.md context and Agent tool
+- **Subagents** — Specialized agents spawned by main sessions (shorter TTL)
+- **Teammates** — Agents that are part of a Claude Code team
+
+Agent classification uses heuristics (system prompt markers, tool count, model tier) and links children to parents via temporal ordering, team config, or content matching. View the live topology:
+
+```bash
+cortex agents topology
+```
+
+## Claude Code Statusline
+
+Cortex includes a statusline script for Claude Code that shows real-time pipeline status with gradient colors:
+
+```
+◆ Cortex ── Snagged a request ── [████████░░] 72% ── 12.4K saved ── 3 injections
+```
+
+The statusline shows pipeline phase, context bar, tokens saved, and agent info. Enable it through `cortex setup` or configure manually in `~/.claude/settings.json`.
+
+## Dashboard & Management API
+
+Cortex runs a management API on port 9091 (configurable) with a built-in HTML dashboard:
+
+```bash
+# Open dashboard
+open http://localhost:9091
+
+# API endpoints
+curl http://localhost:9091/api/status
+curl http://localhost:9091/api/brain/summary
+curl http://localhost:9091/api/agents
+curl http://localhost:9091/api/agents/topology
+curl http://localhost:9091/api/statusline
+```
+
+SSE streams available at `/api/logs/stream` and `/api/pipeline/live`.
+
+## CLI
+
+```bash
+cortex start [-d] [--port N]     # Start daemon (foreground or detached)
+cortex stop                      # Graceful shutdown
+cortex status                    # Query running daemon or show config
+cortex setup                     # Interactive config wizard (TUI)
+cortex brain <subcommand>        # list | search | stats | import | sources
+cortex features <subcommand>     # list | enable | disable
+cortex logs [-n N] [--follow]    # View or stream JSONL logs
+cortex config <subcommand>       # show | path | set (dotted key syntax)
+cortex agents <subcommand>       # list | topology | history | detail <id>
+```
+
+## Configuration
+
+Cortex reads from `~/.cortex/config.yaml` with sensible defaults:
+
+```yaml
+proxyPort: 9090
+targetBaseUrl: "https://api.anthropic.com"
+dashboardPort: 9091
+brainDir: "./brain/entries"
+dataDir: "~/.cortex"
+pruneThresholdTokens: 500
+injectionConfidenceThreshold: 0.9
+rrfWeights:
+  featureOverlap: 0.5
+  semantic: 0.5
+agentTracking:
+  maxActive: 1000
+  maxHistory: 100
+  subagentTtlMs: 300000    # 5 min
+  mainTtlMs: 3600000       # 1 hr
+  teammateTtlMs: 3600000   # 1 hr
+```
+
+Environment overrides: `CORTEX_PORT`, `CORTEX_TARGET_URL`, `CORTEX_DASHBOARD_PORT`.
+
+## Session Logs
+
+Every request is logged as JSONL to `~/.cortex/logs/session-{date}.jsonl` with fingerprint data, match scores, injection decisions, agent classification, and processing time.
+
+## Development
+
+```bash
+npm run dev          # Start with tsx
+npm run build        # TypeScript compile
+npm test             # Run vitest (41 test files)
+npx tsc --noEmit     # Type-check
+```
+
+**Note:** Embedding tests require single-fork mode due to ONNX model file locks:
+```bash
+npx vitest run --pool=forks --poolOptions.forks.singleFork
+```
+
+## Requirements
+
+- Node.js 20+
+- `better-sqlite3` requires native compilation (VS C++ build tools on Windows)
+- First run downloads BGE-small ONNX model (~130MB) to `~/.cortex/models/`
+
+## Project Structure
+
+```
+src/
+├── proxy/           HTTP server, body buffering, HTTPS forwarding, SSE passthrough, token cache
+├── context/         Message parser, token estimator, pruner, injector
+├── fingerprint/     Rule extraction, BGE-small embedder, composite fingerprint
+├── matcher/         Feature overlap, cosine similarity, RRF fusion
+├── brain/           SQLite store, Markdown+YAML loader, multi-source adapters
+├── agents/          Agent detection, classification, parent linking, team reader, state registry
+├── core/            CortexCore orchestrator, event emitter, feature manager, accumulator, logger
+├── cli/             Router, commands, console renderer, wizard, Claude settings bridge
+├── api/             Management REST API + SSE streams
+├── dashboard/       Static HTML dashboard
+├── tui/             Interactive config screen (panels, fields, renderer)
+├── statusline/      Pipeline phase phrases and gradient colors
+└── types/           Shared type contracts (Anthropic API, Fingerprint, Brain, Agents, Events)
+
+bin/cortex-statusline   Node.js statusline script for Claude Code
+brain/entries/          13 seed brain entries (Markdown + YAML frontmatter)
+tests/                  Unit + integration tests (41 test files)
+```
+
+## License
+
+MIT

package/brain/cortex-brain.yaml

@@ -0,0 +1,3 @@
+name: "cortex-default"
+version: "0.1.0"
+description: "Default brain directory shipped with Cortex"

package/brain/entries/bash-permission-denied.md

@@ -0,0 +1,100 @@
+---
+id: bash-permission-denied
+title: "Bash permission denied errors"
+language: bash
+error_types: ["Permission denied", "EACCES"]
+tags: [debugging, bash, permissions, linux]
+---
+
+## Problem
+
+Running a script or accessing a file fails with `Permission denied` or `EACCES`.
+
+## Common Causes & Fixes
+
+### 1. Script not executable
+
+```bash
+ls -la script.sh
+# -rw-r--r--  (no x bit)
+
+chmod +x script.sh
+./script.sh  # Now works
+```
+
+### 2. Missing shebang
+
+Even with the execute bit, the script needs a shebang line:
+
+```bash
+#!/usr/bin/env bash
+echo "Hello"
+```
+
+Without it, the OS does not know which interpreter to use. You can also run it explicitly:
+
+```bash
+bash script.sh
+```
+
+### 3. Wrong ownership
+
+```bash
+ls -la /path/to/file
+# Shows owner:group
+
+# Change ownership
+sudo chown $USER:$USER /path/to/file
+
+# Or change just for the directory
+sudo chown -R $USER:$USER /path/to/directory
+```
+
+### 4. File in a restricted directory
+
+Directories need the execute bit (`x`) for traversal:
+
+```bash
+chmod +x /path/to/directory
+```
+
+### 5. npm global install fails with EACCES
+
+Do not use `sudo npm install -g`. Fix the npm prefix instead:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+# Add to ~/.bashrc or ~/.zshrc:
+export PATH=~/.npm-global/bin:$PATH
+```
+
+Or use `npx` to avoid global installs entirely.
+
+### 6. Docker volume permission mismatch
+
+Files created inside a container may have root ownership on the host:
+
+```bash
+sudo chown -R $USER:$USER ./data
+```
+
+Or run the container with your UID:
+
+```bash
+docker run --user $(id -u):$(id -g) myimage
+```
+
+## `sudo` vs `chown`
+
+- **`sudo`** runs a single command as root — use for one-off admin tasks
+- **`chown`** changes file ownership permanently — use when your user should own the file
+- Prefer `chown` over repeatedly using `sudo` for files in your project
+
+### Quick Checklist
+
+- `ls -la` to check permissions and ownership
+- `chmod +x` to add execute permission
+- `chown $USER` to fix ownership
+- Add shebang (`#!/usr/bin/env bash`) to scripts
+- Never `sudo npm install -g` — fix npm prefix instead

package/brain/entries/cors-preflight.md

@@ -0,0 +1,98 @@
+---
+id: cors-preflight
+title: "CORS preflight errors"
+language: javascript
+error_types: ["CORS", "Access-Control-Allow-Origin", "preflight", "blocked by CORS policy"]
+tags: [debugging, cors, http, api, express]
+---
+
+## Problem
+
+Browser blocks a request with `blocked by CORS policy`. The server does not include the correct `Access-Control-Allow-Origin` header, or the preflight OPTIONS request fails.
+
+## What Is CORS
+
+Cross-Origin Resource Sharing is a browser security feature. When JavaScript on `http://localhost:3000` calls an API on `http://localhost:8080`, the browser enforces CORS because the origins differ (different port = different origin).
+
+The browser sends a **preflight** OPTIONS request first for non-simple requests (custom headers, PUT/DELETE, JSON content-type). The server must respond with the correct CORS headers.
+
+## Fix: Express cors Middleware
+
+```bash
+npm install cors
+```
+
+```javascript
+import cors from 'cors';
+import express from 'express';
+
+const app = express();
+
+// Allow all origins (development only)
+app.use(cors());
+
+// Or restrict to specific origins (production)
+app.use(cors({
+  origin: ['http://localhost:3000', 'https://myapp.com'],
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  allowedHeaders: ['Content-Type', 'Authorization'],
+  credentials: true,
+}));
+```
+
+## Fix: Manual Headers
+
+If you cannot use the middleware:
+
+```javascript
+app.use((req, res, next) => {
+  res.header('Access-Control-Allow-Origin', 'http://localhost:3000');
+  res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+  res.header('Access-Control-Allow-Credentials', 'true');
+  if (req.method === 'OPTIONS') {
+    return res.sendStatus(204);
+  }
+  next();
+});
+```
+
+The key: you must handle the OPTIONS method and return the headers.
+
+## Fix: Dev Proxy (Avoids CORS Entirely)
+
+Use your frontend dev server to proxy API requests — same origin, no CORS:
+
+**Vite:**
+
+```javascript
+// vite.config.js
+export default {
+  server: {
+    proxy: {
+      '/api': 'http://localhost:8080',
+    },
+  },
+};
+```
+
+**Create React App:**
+
+```json
+{
+  "proxy": "http://localhost:8080"
+}
+```
+
+## Common Gotchas
+
+- `credentials: true` requires a specific origin — `*` is not allowed with credentials
+- The `Origin` header is set by the browser and cannot be overridden by JavaScript
+- CORS errors in the console mean the server is wrong, not the client
+
+### Quick Checklist
+
+- Install and configure `cors` middleware
+- Handle OPTIONS preflight requests
+- Use a dev proxy to avoid CORS during development
+- Set specific origins (not `*`) when using credentials

package/brain/entries/docker-port-conflict.md

@@ -0,0 +1,99 @@
+---
+id: docker-port-conflict
+title: "Docker and system port conflicts"
+language: general
+error_types: ["address already in use", "port is already allocated", "EADDRINUSE"]
+tags: [debugging, docker, networking, ports]
+---
+
+## Problem
+
+Starting a server or container fails with `address already in use`, `port is already allocated`, or `EADDRINUSE`. Another process is already listening on that port.
+
+## Find What Is Using the Port
+
+### Linux / macOS
+
+```bash
+lsof -i :3000
+# or
+ss -tlnp | grep 3000
+```
+
+### Windows
+
+```powershell
+netstat -ano | findstr :3000
+```
+
+### Docker specifically
+
+```bash
+docker ps --format "table {{.Names}}\t{{.Ports}}"
+```
+
+## Kill the Process
+
+```bash
+# Using the PID from lsof output
+kill -9 <PID>
+```
+
+Or stop a Docker container:
+
+```bash
+docker stop <container-name>
+```
+
+## Fix Docker Port Mapping
+
+If two containers or a container and a host process collide, change the host port mapping:
+
+```yaml
+# docker-compose.yml
+services:
+  web:
+    ports:
+      - "3001:3000"  # Changed host port from 3000 to 3001
+```
+
+Or on the command line:
+
+```bash
+docker run -p 3001:3000 myimage
+```
+
+The format is `HOST:CONTAINER` — change the left side to an available port.
+
+## Prevent Recurring Conflicts
+
+1. **Use `.env` for port config** so different developers can use different ports:
+
+```env
+PORT=3000
+```
+
+```yaml
+ports:
+  - "${PORT}:3000"
+```
+
+2. **Stop old containers** before starting new ones:
+
+```bash
+docker compose down
+docker compose up -d
+```
+
+3. **Check before starting:**
+
+```bash
+lsof -i :3000 || echo "Port 3000 is free"
+```
+
+### Quick Checklist
+
+- `lsof -i :PORT` to find the conflicting process
+- `kill -9 <PID>` or `docker stop` to free the port
+- Change the host port mapping if both services need to run
+- `docker compose down` before `up` to avoid stale containers

package/brain/entries/env-vars-missing.md

@@ -0,0 +1,107 @@
+---
+id: env-vars-missing
+title: "Environment variables not loading"
+language: general
+error_types: ["undefined", "env var not set", "missing environment variable", "ENOENT .env"]
+tags: [debugging, env, dotenv, configuration]
+---
+
+## Problem
+
+Application reads `undefined` for environment variables that should be set. The `.env` file exists but values are not reaching the process.
+
+## Fix by Runtime
+
+### Node.js (dotenv)
+
+```bash
+npm install dotenv
+```
+
+```javascript
+// At the very top of your entry point
+import 'dotenv/config';
+
+console.log(process.env.DATABASE_URL);
+```
+
+Or with Node 20.6+, use the built-in flag:
+
+```bash
+node --env-file=.env src/index.js
+```
+
+### Python
+
+```bash
+pip install python-dotenv
+```
+
+```python
+from dotenv import load_dotenv
+import os
+
+load_dotenv()  # Reads .env from current directory
+
+db_url = os.environ["DATABASE_URL"]
+# or with a default:
+db_url = os.environ.get("DATABASE_URL", "sqlite:///local.db")
+```
+
+### Shell
+
+Variables in `.env` are not automatically exported. Source the file:
+
+```bash
+export $(grep -v '^#' .env | xargs)
+```
+
+Or set inline:
+
+```bash
+export DATABASE_URL=postgres://localhost:5432/mydb
+```
+
+Add to `~/.bashrc` or `~/.zshrc` for persistence across sessions.
+
+### Docker
+
+```bash
+docker run --env-file .env myimage
+```
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    env_file:
+      - .env
+```
+
+## `.env` File Format
+
+```env
+# Comments start with #
+DATABASE_URL=postgres://localhost:5432/mydb
+API_KEY=sk-abc123
+NODE_ENV=development
+```
+
+Rules:
+- No spaces around `=`
+- No quotes needed (unless value contains spaces)
+- One variable per line
+- Lines starting with `#` are comments
+
+## Common Gotchas
+
+- `.env` is not committed to git — make sure it exists locally (use `.env.example` as a template)
+- `dotenv` must be imported before any code that reads `process.env`
+- Docker Compose interpolates `${VAR}` in `docker-compose.yml` from the host `.env`, not the container's
+
+### Quick Checklist
+
+- Verify `.env` file exists and has correct format
+- Load dotenv at the top of entry point
+- Use `--env-file` for Docker
+- `export` for shell — variables are not exported by default