MCP-CORTEX-INTELLIGENT
// MAKE ORDINARY LLMS SMARTER — OFFLINE · NO API KEYS · NO CLOUD
Cortex Intelligent is an MCP server that augments an ordinary LLM with context, procedures, memory, exemplars, verification, and an internal decision engine. Everything runs locally. No API keys. No cloud. No model gateway. The model becomes smarter by following structured guardrails and checking real execution feedback.
OFFLINE-FIRST
NO API KEYS
61 TOOLS
STDIO MCP
MIT LICENSE
NODE >= 22.12
62MCP Tools
259Tests Passing
0API Keys
100%Offline
Features
Auto-Provision Agent & Skill
Idempotent marker-block append. Never overwrites user content. Backup before write.
Model Awareness + Guardrails
Detects model tier (weak/medium/strong) and injects anti-blunder procedures.
Offline Cognitive Augmentor
Exemplar retrieval, structured self-critique, compliance scoring, verification runner.
Internal Decision Engine
Fast deterministic decisions (tier/risk/route/compliance) via heuristics. No LLM.
Plan & Task Management
AI Agent → SKILL.md → AGENTS.md → PLAN.md ↔ CORTEX_EXECUTE ↔ TASK.md ↔ CORTEX_VERIFY → DONE. Persistent task tracking.
Knowledge Base + Memory
Hybrid search (BM25 + vector + RRF), long-term memory with decay.
Installation
Requirements
- Node.js >= 22.12 (for node:sqlite)
- npm
From source
git clone https://github.com/adyoi/mcp-cortex-intelligent.git
cd mcp-cortex-intelligent
npm install
npm run build
npm start
From npm (after publish)
npx mcp-cortex-intelligent
Configuration
Copy .env.example to .env and edit. Environment variables always win over the file.
| Variable | Default | Purpose |
|---|---|---|
| CORTEX_DB_DIR | .cortex-data | SQLite store location |
| CORTEX_MODEL | (auto) | Override model |
| CORTEX_TIER_OVERRIDE | (auto) | Override tier |
| CORTEX_VERIFY_ALLOWLIST | npm test,npm run lint,npm run typecheck | Verification commands |
| CORTEX_VERIFY_TIMEOUT_MS | 300000 | Verification timeout |
| CORTEX_SELF_CRITIQUE_THRESHOLD | 0.8 | Revision threshold |
| CORTEX_SELF_CRITIQUE_MAX_ITERS | 3 | Max self-critique iterations |
| CORTEX_PROVISION_BACKUP | 1 | Backup before write |
| CORTEX_GUARDRAILS_STRICT | 1 | Enforce guardrails |
| EMBEDDING_PROVIDER | local | local / transformers |
| EMBEDDING_MODEL | Xenova/all-MiniLM-L6-v2 | Embedding model |
| SEARCH_MODE | hybrid | hybrid / vector / keyword |
| KB_MEMORY_HALF_LIFE_DAYS | 14 | Memory decay half-life |
OpenCode registration
Add to ~/.config/opencode/opencode.json:
{
"mcp": {
"cortex": {
"type": "local",
"command": ["node", "~/mcp-cortex-intelligent/dist/index.js"],
"cwd": "~/mcp-cortex-intelligent",
"environment": { "CORTEX_DB_DIR": "~/mcp-cortex-intelligent/.cortex-data" }
}
}
}
Tools (62)
| # | Tool | Purpose |
|---|---|---|
| 1 | system_stats | DB, embedding, counts, verifier status |
| 2 | lsp_diagnostics | Run language-server-style diagnostics (tsc/pyright/cargo/go vet) |
| 3 | cognitive_status | Session summary: model, tier, calls, scores, verification, decision |
| 4 | bootstrap_session | Detect root, provision agent+skill, record session state |
| 5 | provision_agent_skill | Provision or append (idempotent, force version) |
| 6 | list_agents_skills | Inventory agent/skill files + auto-block versions |
| 7 | update_procedure_block | Update auto block with new version |
| 8 | detect_model | Detect model from env/config/arg |
| 9 | get_model_profile | Profile & tier of a model |
| 10 | set_model | Override model for session |
| 11 | get_guardrails | Procedure + anti-blunder + verification (injectable) |
| 12 | model_decision | Internal tier/risk/route/needsVerify decision |
| 13 | knowledge_ingest_text | Ingest text |
| 14 | knowledge_ingest_file | Ingest file |
| 15 | knowledge_ingest_dir | Ingest directory |
| 16 | knowledge_search | Hybrid search (BM25 + vector + RRF) |
| 17 | knowledge_retrieve | Ready-to-inject context block + token count |
| 18 | knowledge_list_documents | List documents (paginated) |
| 19 | knowledge_document_stats | Document storage statistics |
| 20 | knowledge_delete_document | Delete document + chunks + FTS |
| 21 | knowledge_sync_session | Ingest OpenCode session inputs |
| 22 | knowledge_reindex | Re-embed all vectors in place |
| 23 | knowledge_backup | Consistent SQLite snapshot (VACUUM INTO) |
| 24 | memory_remember | Save long-term memory |
| 25 | memory_recall | Semantic memory search (decay + recall count) |
| 26 | memory_context | Compact context block from memories |
| 27 | memory_list | List memories (filter type/tag/importance) |
| 28 | memory_get | Get memory by id |
| 29 | memory_update | Update memory content/type/importance/tags |
| 30 | memory_forget | Delete memory |
| 31 | memory_consolidate | Dedupe + promote hot memories |
| 32 | memory_stats | Counts, tokens, importance, by type |
| 33 | self_critique | Checklist + scoring + issues (no LLM) |
| 34 | score_compliance | Check completeness of required steps |
| 35 | run_verification | Run allowlisted test/lint/typecheck |
| 36 | decision_classify | Internal decision (tier/risk/route/compliance) |
| 37 | decision_health | Health of internal decision engine |
| 38 | get_procedure | Get procedure by name |
| 39 | list_procedures | List all procedures |
| 40 | ingest_procedure | Store a new procedure |
| 41 | retrieve_exemplars | Retrieve best exemplars for a task |
| 42 | ingest_exemplar | Store a high-quality exemplar |
| 43 | init_plan | Initialize PLAN.md if missing (idempotent) |
| 44 | read_plan | Read PLAN.md content |
| 45 | update_plan_section | Update a PLAN.md section by heading |
| 46 | init_task | Initialize TASK.md if missing (idempotent) |
| 47 | init_agents | Initialize AGENTS.md if missing (idempotent) |
| 48 | init_audit | Initialize AUDIT.md if missing (idempotent) |
| 49 | task_create | Create a new task |
| 50 | task_list | List tasks (filter status/priority) |
| 51 | task_get | Get task by id |
| 52 | task_start | Set task status to doing |
| 53 | task_done | Set task status to done |
| 54 | task_block | Set task status to blocked + reason |
| 55 | task_delete | Delete a task |
| 56 | task_update | Update task title/priority/owner/plan_ref/notes |
| 57 | task_sync_md | Write TASK.md from DB |
| 58 | task_summary | Summary of task statuses |
| 59 | task_from_plan | Auto-generate tasks from PLAN.md step/bullet lines |
| 60 | webfetch | Fetch URL (with SSRF guard, timeout, ingest option) |
| 61 | webfetch_validate | Validate URL for webfetch (no fetch) |
| 62 | browser_fetch | Fetch URL via headless browser (playwright/puppeteer), falls back to webfetch |
Workflow
Bootstrap Session
- Call
bootstrap_session(project_root). - Detect model →
model_decision→ set session state. - Provision agent & skill (append if exists).
- Inject guardrails via
get_guardrails(task="session_start").
Task Execution
get_guardrails(task_type)→ checklist.retrieve_exemplars(task)→ best examples.- Plan → Read → Edit → Verify → Review.
run_verification()→ real feedback.score_compliance(plan)+self_critique(artifact).
Plan & Task Loop
init_plan+init_task.- Agent reads PLAN.md → picks next task.
task_list(status="todo")→ choose.task_start(id)→ doing.- Execute with guardrails + verification.
task_done(id)after verification passes.task_sync_md()→ write TASK.md.
flowchart LR
A[AI Agent] --> B[SKILL.md]
B --> C[AGENTS.md]
C --> D[memory_context]
D --> E[PLAN.md]
E --> F[get_guardrails]
F --> G[CORTEX_EXECUTE]
G <--> H[TASK.md]
H <--> I[CORTEX_VERIFY]
I -- pass --> J[DONE]
I -- fail --> G
Security
- Secrets are never stored (no-secret rule).
- Verification runner uses allowlist, locked cwd, timeout, minimal env.
- Provisioning restricted to
.opencode/under project root. - Backup before overwrite; idempotent writes.
- 100% offline, no network calls.
Troubleshooting
Tools not showing up
Check config filename (opencode.json), location (global: ~/.config/opencode/opencode.json), cwd, and CORTEX_DB_DIR. Restart OpenCode.
Slow first start
tsx compiles TypeScript on first run; subsequent calls are fast. Use compiled dist/ entry.
Verification runner blocked
Only allowlisted commands run. Adjust CORTEX_VERIFY_ALLOWLIST.
Development
npm install
npm run typecheck
npm run lint
npm run build
npm test
npm start