Offline MCP server that makes ordinary LLMs smarter by adding context, procedures, memory, exemplars, verification, and deterministic decision support.
Provision agent/skill files and bootstrap sessions idempotently.
Detect/configure model tier, inject anti-blunder guardrails, and run internal decisions.
Ingest, search, retrieve, reindex, and back up knowledge documents with hybrid BM25/vector search.
Store, recall, update, consolidate, and manage long-term memories.
Manage procedures and retrieve/ingest exemplars.
Run self-critique, compliance scoring, and allowlisted verification commands.
Manage plans and tasks (PLAN/TASK/AGENTS/AUDIT) with task lifecycle and Markdown sync.
Fetch web pages or use a headless browser; validate URLs with SSRF guard.
Check system stats, cognitive status, and language-server-style diagnostics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cortex Intelligent remember we deploy on fridays, then search my knowledge base"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Make ordinary LLMs smarter — offline, no API keys, no external services.
MCP server that augments an ordinary LLM with context, procedures, memory, exemplars, verification, and an internal decision engine. Standard MCP (stdio), compatible with OpenCode, Claude Desktop, Cursor, VS Code, and any MCP client.
flowchart TB
Client["MCP Client (OpenCode)"] -->|stdio| Server["Cortex MCP Server (offline)"]
Server --> Provisioner["Provisioner<br/>agent and skill, marker-block"]
Server --> ModelGuard["Model Guard<br/>resolver, guardrails, decision"]
Server --> CogAug["Cognitive Augmentor<br/>exemplar, self-critique, compliance, verifier"]
Server --> KB["Knowledge Base<br/>hybrid search plus memory"]
Server --> Decision["Internal Decision Engine<br/>heuristics"]
Server --> SQLite[("SQLite + FTS5")]
Server --> Verifier["Verification Runner<br/>allowlist, sandbox"]Related MCP server: jev-super-agent
Auto-Provision Agent & Skill — idempotent marker-block append, never overwrites user content, backup before write.
Model Awareness + Guardrails — detects model tier (weak/medium/strong), 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.
Node.js >= 22.12 (for node:sqlite)
npm
git clone https://github.com/adyoi/mcp-cortex-intelligent.git
cd mcp-cortex-intelligent
npm install
npm run build
npm startnpx mcp-cortex-intelligentCopy .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_VERIFY_CWD | (project root) | Working directory for verification |
CORTEX_LOG_LEVEL | info | Log level (error/warn/info/debug) |
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 |
KB_PRUNE | 0 | Prune stale memories on consolidate |
KB_VECTOR_CACHE_WARN_MB | 256 | Vector cache warning threshold (MB) |
KB_SESSION_MAX_MSGS | 500 | Max session messages ingested |
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" }
}
}
}Group | Count | Tools |
System | 3 | system_stats, lsp_diagnostics, cognitive_status |
Provisioning | 4 | bootstrap_session, provision_agent_skill, list_agents_skills, update_procedure_block |
Model | 5 | detect_model, get_model_profile, set_model, get_guardrails, model_decision |
Knowledge | 11 | knowledge_ingest_text, knowledge_ingest_file, knowledge_ingest_dir, knowledge_search, knowledge_retrieve, knowledge_list_documents, knowledge_document_stats, knowledge_delete_document, knowledge_sync_session, knowledge_reindex, knowledge_backup |
Memory | 9 | memory_remember, memory_recall, memory_context, memory_list, memory_get, memory_update, memory_forget, memory_consolidate, memory_stats |
Cognitive | 3 | self_critique, score_compliance, run_verification |
Decision | 2 | decision_classify, decision_health |
Procedure | 5 | get_procedure, list_procedures, ingest_procedure, retrieve_exemplars, ingest_exemplar |
Plan & Task | 17 | init_plan, read_plan, update_plan_section, init_task, init_agents, init_audit, task_create, task_list, task_get, task_start, task_done, task_block, task_delete, task_update, task_sync_md, task_summary, task_from_plan |
Web | 3 | webfetch, webfetch_validate, browser_fetch |
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").
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).
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 --> Ginit_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.
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.
npm install
npm run typecheck
npm run lint
npm run build
npm test
npm startFull documentation: https://adyoi.github.io/mcp-cortex-intelligent/
See CONTRIBUTING.md and SECURITY.md.
MIT
Bootstrap a session: detect model, provision agent & skill, record state.
Inputs: project_root (required).
Fetch a URL using a headless browser (JS-rendered, screenshots). Requires optional playwright/puppeteer; falls back to webfetch when unavailable.
Inputs: url (required), max_chars, timeout_ms.
Cognitive status summary for the current session.
Inputs: project_root.
Internal decision classification (tier/risk/route/compliance).
Inputs: state (required), questions.
Health of the internal decision engine.
Inputs: no named parameters.
Detect the model in use from env/config/arg.
Inputs: model, project_root.
Get procedure guardrails (anti-blunder) for a task/model.
Inputs: task (required), model, project_root.
Get model profile (tier, capabilities, blunder patterns) from the registry.
Inputs: model (required).
Get a procedure by name.
Inputs: name (required).
Ingest a high-quality exemplar.
Inputs: title (required), content (required), outcome (required), language (required), +1 more.
Ingest a new procedure.
Inputs: name (required), content (required), version (required), tags.
Initialize AGENTS.md if missing (idempotent).
Inputs: project_root (required).
Initialize AUDIT.md if missing (idempotent).
Inputs: project_root (required).
Initialize PLAN.md if missing (idempotent).
Inputs: project_root (required).
Initialize TASK.md if missing (idempotent).
Inputs: project_root (required).
Snapshot the store to a consistent SQLite file (VACUUM INTO, safe under WAL) and report its integrity. Refuses to overwrite an existing file. Restore is done offline via 'cli restore ' while the server is stopped.
Inputs: target_path.
Delete a document and all its chunks by ID
Inputs: doc_id (required).
Document storage statistics
Inputs: no named parameters.
Recursively ingest supported source files from a directory
Inputs: path (required), recursive, extensions.
Read a file and store it as a knowledge document. Honours KB_ALLOWED_DIRS when set.
Inputs: path (required), metadata.
Store raw text as a knowledge document (chunked + embedded for later retrieval)
Inputs: title (required), content (required), metadata, contentType.
List stored knowledge documents (newest first, paginated)
Inputs: limit, offset.
Re-embed every stored vector for the currently configured EMBEDDING_PROVIDER/MODEL. Use after changing the embedding model or dimension to migrate the existing store in place instead of wiping and re-ingesting. Searches are blocked while it runs; re-run to resume after an interruption.
Inputs: batch_size.
Retrieve relevant context chunks as a ready-to-inject context block for the LLM. Prefer this over knowledge_search when the result will be used as context.
Inputs: query (required), top_k, doc_id, source, +1 more.
Hybrid semantic + keyword search over stored documents. Returns chunks ranked by relevance with scores. Set explain to see per-leg scores (vector cosine, keyword BM25, RRF contribution) and diagnose ranking. Optional alpha (0..1) tips the balance: 0 = keyword-only, 1 = vector-only, in between blends 'alpha * cosine + (1-alpha) * BM25'. Default uses Reciprocal Rank Fusion.
Inputs: query (required), alpha, top_k, doc_id, +3 more.
Ingest an opencode session's user inputs (or the latest active session) into the knowledge store as searchable documents. Use with the session id from opencode, or omit session_id and pass directory to auto-pick the most recent session in that workspace.
Inputs: limit, directory, session_id.
List agent & skill files and their auto-block versions.
Inputs: project_root (required).
List all procedures.
Inputs: no named parameters.
Run language-server-style diagnostics (tsc/pyright/cargo check/go vet) and return structured, location-aware issues.
Inputs: project_root.
Deduplicate near-identical memories, boost frequently-used ones, and optionally prune stale memories (enable with env KB_PRUNE=1)
Inputs: no named parameters.
Build a compact context block from the most relevant memories for a given topic. Best for injecting memory into prompts.
Inputs: topic (required), top_k.
Delete a memory by ID
Inputs: id (required).
Get a single memory by ID
Inputs: id (required).
List memories, optionally filtered by type, tag, or minimum importance
Inputs: tag, type, limit, min_importance.
Semantically search long-term memories relevant to a query. This is how you remember past context.
Inputs: query (required), top_k, min_score.
Store a piece of long-term memory (fact, decision, preference, instruction, task, insight, conversation). Use this to persist things that should be remembered across sessions.
Inputs: content (required), tags, type, importance.
Long-term memory statistics (count, tokens, importance, by type)
Inputs: no named parameters.
Update content / type / importance / tags of an existing memory
Inputs: id (required), tags, type, content, +1 more.
Internal model decision: tier/risk/route/needsVerify.
Inputs: task (required), files, model, project_root.
Provision or append agent & skill files (idempotent).
Inputs: project_root (required), force_version.
Read PLAN.md content.
Inputs: project_root (required), full.
Retrieve best exemplars for a task (optionally filtered by task_type).
Inputs: task (required), top_k, task_type.
Run allowlisted verification commands (test/lint/typecheck).
Inputs: cwd, commands, timeout_ms.
Score procedure compliance of a plan/diff.
Inputs: plan (required).
Structured self-critique (weighted checklist + scoring + severity + verdict) without LLM.
Inputs: artifact (required), tier.
Override the model for this session (env-level hint).
Inputs: model (required).
Get overall system stats: DB location, documents, chunks, memories, tokens, embedding backend
Inputs: no named parameters.
Set task status to blocked with reason.
Inputs: id (required), reason (required).
Create a new task.
Inputs: title (required), owner, plan_ref, priority.
Delete a task.
Inputs: id (required).
Set task status to done.
Inputs: id (required).
Auto-generate tasks from PLAN.md step/bullet lines.
Inputs: project_root (required).
Get task by id.
Inputs: id (required).
List tasks, optionally filtered by status/priority, with pagination.
Inputs: limit, offset, status, priority.
Set task status to doing.
Inputs: id (required).
Summary of task statuses.
Inputs: no named parameters.
Sync TASK.md from DB.
Inputs: project_root (required).
Update task title/priority/owner/plan_ref/notes.
Inputs: id (required), notes, owner, title, +2 more.
Update a PLAN.md section by heading.
Inputs: content (required), heading (required), project_root (required).
Update the auto block in agent & skill files with a new version.
Inputs: version (required), project_root (required).
Fetch a public http/https URL and return its title + readable text. Private/loopback hosts are refused. Use ingest: true to also store the page in the knowledge base.
Inputs: url (required), ingest, source, max_chars, +1 more.
Validate a URL for webfetch (protocol + SSRF guard) without fetching it.
Inputs: url (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 62 tools
Most tools target distinct resources and actions across memory, knowledge, tasks, procedures, and session management. A few clusters overlap, such as knowledge_search vs knowledge_retrieve, webfetch vs browser_fetch, and the decision/model diagnostic tools, but their descriptions generally clarify the distinction.
The set is predominantly snake_case with predictable domain/action naming such as task_create, memory_recall, and knowledge_ingest_file. Minor deviations exist, including webfetch/browser_fetch without a clear domain prefix and noun-first names like memory_stats mixed with verb-first names like get_procedure.
62 tools is far above a reasonable scoped surface for this server and spans many loosely related areas. Several tools could likely be consolidated or moved to separate services, making the surface heavy for an agent to navigate.
Core domains have broad coverage: memory has full CRUD plus consolidation/context, knowledge has ingest/search/list/delete/backup/reindex, and tasks have full lifecycle operations. There are minor lifecycle gaps for procedures and exemplars, which lack obvious update/delete/list management operations, but core workflows are well covered.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
