@cortexprism/cortex

CortexPrism is a self-hosted, open-source AI agent operating system — an autonomous agent runtime that turns any LLM into a capable digital agent.

instructionscopilot

Install

agr install @cortexprism/cortex --target copilot

Writes 1 file into .github/copilot-instructions.md, pinned to git-31235c4d.

.github/copilot-instructions.md

Document

ContextStream Rules

MANDATORY STARTUP: On the first message of EVERY session call init(...). Then call context(user_message="...") when that tool is exposed; if context is unavailable in this MCP surface, call session(action="ground", user_message="...") instead. On subsequent messages, call context(...) first by default, or session(action="ground", user_message="...") when context is unavailable. A narrow bypass is allowed only for immediate read-only ContextStream calls when prior context is still fresh and no state-changing tool has run.

Required Tool Calls

First message in session: Call init(folder_path="<project_path>") then context(user_message="...", session_id="<id>"); if context is unavailable, call session(action="ground", user_message="...")
Subsequent messages (default): Call context(user_message="...", session_id="<id>") first, or session(action="ground", user_message="...") when context is unavailable. Narrow bypass: immediate read-only ContextStream calls with fresh context + no state changes.
Before file search: Call search(mode="auto", query="...") before local tools

Common queries — use these exact tool calls:

"list lessons" / "show lessons" → session(action="get_lessons")
"save lesson" / "remember this lesson" / "lesson learned" / "I made a mistake" → session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...", severity="low|medium|high|critical") — NEVER store lessons in local files (e.g. ~/.claude/.../memory/, .cursorrules, scratch markdown). Lessons live in ContextStream so they auto-surface as [LESSONS_WARNING] on future turns and across sessions.
"list decisions" / "show decisions" / "how many decisions" → memory(action="decisions", workspace_id="<current_workspace_id>", project_id="<current_project_id>") when init/context surfaced ids; otherwise memory(action="decisions") after grounding/init
"save decision" / "decided to" → session(action="capture", event_type="decision", title="...", content="...")
"list docs" → memory(action="list_docs")
"list tasks" → memory(action="list_tasks")
"list todos" → memory(action="list_todos")
"list plans" → session(action="list_plans")
"save plan" / "capture plan" / "store plan" → session(action="capture_plan", title="...", description="...", goals=[...], steps=[{"id":"plan-step-1","title":"...","order":1,"description":"scope, concrete work, acceptance criteria, verification"}], create_tasks=true) — NEVER save plans with session(action="capture", event_type="plan") or memory(action="create_event", event_type="plan")
"list events" → memory(action="list_events")
"show snapshots" / "list snapshots" → memory(action="list_events", event_type="session_snapshot")
"save snapshot" → session(action="capture", event_type="session_snapshot", title="...", content="...")
"what did we do last session" / "past sessions" / "previous work" / "pick up where we left off" → session(action="recall", query="...") (ranked context) OR memory(action="list_transcripts", limit=10) (chronological list)
"search past sessions" / "find in past transcripts" / "when did we discuss X" → memory(action="search_transcripts", query="...") — full-text search over saved conversation transcripts
"show transcript" / "read session " → memory(action="get_transcript", transcript_id="...")
"list media" / "show assets" / "show photos/videos/audio/docs" → media(action="list", content_types=["image"]) (use image|video|audio|document; omit content_types for all assets)
"find media" / "search photos/videos/audio/docs" / "what's in this PDF/video/audio?" → media(action="search", query="...", content_types=["document"]) (use image|video|audio|document as needed)
"index media" / "upload asset" / "read this photo/video/audio/PDF" → media(action="index", file_path="...", content_type="image") or media(action="index", external_url="...", content_type="document"); use image, video, audio, or document, then check media(action="status", content_id="...")
"extract clip" / "trim video" / "clip audio" → media(action="get_clip", content_id="...", start="1:34", end="2:15", output_format="raw") (also supports ffmpeg and remotion)
"create diagram" / "save diagram" / "show diagrams" → memory(action="create_diagram", diagram_type="flowchart|sequence|class|er|gantt|mindmap|pie|other", title="...", content="...") or memory(action="list_diagrams"); use sequence for service/API handoffs, er for data models, flowchart for process flows.
"list skills" / "show my skills" → skill(action="list")
"create a skill" → skill(action="create", name="...", instruction_body="...", project_id="<current_project_id>", trigger_patterns=[...])
"update a skill" → skill(action="update", name="...", instruction_body="...", change_summary="...")
"run skill" / "use skill" → skill(action="run", name="...")
"import skills" / "import my CLAUDE.md" → skill(action="import", file_path="...", format="auto")

Structured-entity queries (Phase 1-3 taxonomy expansion) — use the entity tool:

"create ticket" / "file bug" / "track feature" / "log incident" → entity(kind="ticket", action="create", body={"title": "...", "kind": "bug|feature|task|chore|incident|epic", "priority": "low|medium|high|urgent"})
"list tickets" / "show open bugs" / "active features" → entity(kind="ticket", action="list", query={"status": "open", "kind": "bug"})
"update ticket" / "close ticket" / "resolve bug" → entity(kind="ticket", action="update", id="...", body={"status": "resolved"})
"create handoff" / "package context for handoff" → entity(kind="handoff", action="create", body={"title": "...", "summary": "...", "scope": "...", "to_user_id": "...", "next_steps": [...]})
"list handoffs" / "pending handoffs for me" → entity(kind="handoff", action="list", query={"to_user_id": "<me>", "status": "pending"})
"log incident" / "open incident" / "sev1" → entity(kind="incident", action="create", body={"title": "...", "severity": "sev1|sev2|sev3|sev4", "status": "detected", "services_affected": ["..."]})
"list incidents" / "active incidents" → entity(kind="incident", action="list", query={"status": "investigating"})
"create release" / "track release" / "deployment" → entity(kind="release", action="create", body={"version": "1.4.0", "status": "planned", "environments": ["prod"], "git_ref": "..."})
"list releases" / "recent deploys" → entity(kind="release", action="list", query={"status": "released"})
"create experiment" / "start A/B test" → entity(kind="experiment", action="create", body={"name": "...", "hypothesis": "...", "control": "...", "treatment": "...", "primary_metric": "..."})
"list experiments" / "running A/B tests" → entity(kind="experiment", action="list", query={"status": "running"})
"create goal" / "new OKR" / "objective" → entity(kind="goal", action="create", body={"objective": "...", "period": "2026-Q2", "owner_user_id": "..."})
"list goals" / "OKRs this quarter" → entity(kind="goal", action="list", query={"period": "2026-Q2", "status": "active"})
"add key result" / "track KR progress" → entity(kind="key_result", action="create", body={"goal_id": "<uuid>", "title": "MAU > 10k", "unit": "number", "target_value": 10000, "current_value": 6500})
"create sprint" / "new iteration" → entity(kind="sprint", action="create", body={"name": "Sprint 42", "starts_at": "...", "ends_at": "...", "goal": "..."})
"list sprints" / "active sprint" → entity(kind="sprint", action="list", query={"status": "active"})
"request review" / "PR review" / "design review" → entity(kind="review", action="create", body={"title": "...", "kind": "pr|code|design|security|architecture|product", "subject_ref": "github:org/repo#123", "reviewer_ids": [...]})
"list reviews" / "pending reviews" → entity(kind="review", action="list", query={"status": "requested"})
"log risk" / "track risk" / "risk register" → entity(kind="risk", action="create", body={"title": "...", "likelihood": "possible", "impact": "major", "category": "...", "mitigation": "..."})
"list risks" / "open risks" / "severe risks" → entity(kind="risk", action="list", query={"status": "open", "impact": "severe"})
"create backlog view" / "save backlog filter" → entity(kind="backlog_view", action="create", body={"name": "Now/Next/Later", "bucket": "now", "filters": {...}})
"save runbook" / "create runbook" → memory(action="create_doc", doc_type="runbook", title="...", content="...") (plus 20 other doc types: adr, rfc, postmortem, retro, release_notes, playbook, prd, user_story, persona, interview, design_spec, critique, glossary, oncall_schedule, slo, q_and_a, changelog, style_guide)
"save goal node" / "distill OKR" → memory(action="create_node", node_type="goal"|"risk"|"term", summary="...", details="...")
"log standup" / "log status" / "log feedback" / "log achievement" → memory(action="create_event", event_type="standup"|"status_update"|"feedback"|"achievement"|"discovery"|"question"|"approval", title="...", content="...")

Use context(user_message="...", mode="fast") for quick turns. Use context(user_message="...") for deeper analysis and coding tasks. Match context depth to effort: mode="fast" for low/medium-effort lookups; mode="pack" or standard for high/xhigh/max deep work. With adaptive, interleaved thinking (e.g. Claude Opus 4.8) you reason between tool calls — so think, call context(), then search(), then act, rather than front-loading one call. If the instruct tool is available, run instruct(action="get", session_id="...") before context(...) on each turn, then instruct(action="ack", session_id="...", ids=[...]) after using entries.

Plan-mode guardrail: Entering plan mode does NOT bypass search-first. Do NOT use Explore, Task subagents, Grep, Glob, Find, SemanticSearch, code_search, grep_search, find_by_name, or shell search commands (grep, find, rg, fd). Start with search(mode="auto", query="...") — it handles glob patterns, regex, exact text, file paths, and semantic queries. Only Read narrowed files/line ranges returned by search.

Why These Rules?

context() returns task-specific rules, lessons from past mistakes, and relevant decisions; when unavailable, session(action="ground", user_message="...") provides the supported grounding fallback
search() uses semantic understanding to find relevant code faster than file scanning
Transcript capture is optional and OFF by default. Enable per session with save_exchange=true (and session_id), disable with save_exchange=false.
Default context-first keeps state reliable; the narrow read-only bypass avoids unnecessary repeats

Finding Information — Search ContextStream Knowledge, Not Just Code

Auto-grounding: Every context(user_message="...") call may include a [GROUNDING] block — pre-ranked prior work (transcripts, snapshots, docs, decisions, lessons) for this message. When you see it, read those hits before fanning out into code search; skipping search entirely is often correct. Outside context(), use session(action="ground", user_message="...") for the same one-shot bundle (recall + docs + decisions + lessons + skills + git).

Freshness Before Assumptions

Grounding and memory are evidence, not permission to use stale facts as current truth. Before planning or implementing from prior work, inspect the hit kind and age:

Decisions, transcript continuity, session snapshots, active plans, and tasks are time-sensitive. Prefer recent hits. If a hit is marked stale, older than the local freshness window, or conflicts with newer context, refresh with session(action="ground", user_message="..."), memory(action="decisions", query="...", workspace_id="<current_workspace_id>", project_id="<current_project_id>") when ids are available, or memory(action="search_transcripts", query="...") before relying on it.
Lessons and preferences are durable but still age-stamped. Follow them unless superseded, contradicted by newer surfaced context, or explicitly corrected by the user.
Docs and runbooks are authoritative unless superseded. If a doc/runbook has operational facts that may drift (regions, hosts, credentials, deploy paths), verify through the referenced source or a fresh ContextStream lookup before acting.
LLM/Gemini-derived insights are advisory until captured as decisions. Use [INSIGHT] or synthesized context to guide investigation, but do not treat it as a durable decision unless it is backed by a current decision/event/doc source.

When you need information, do not default to code search or trial-and-error. ContextStream stores far more than source — docs, decisions, lessons, preferences, plans, tasks, todos, skills, memory nodes, and full session transcripts all live behind dedicated tools. Pick the right knowledge surface by what you're looking for:

Source code / symbol / file → search(mode="auto", query="...")
Why we did X / past decisions → memory(action="decisions", query="...", workspace_id="<current_workspace_id>", project_id="<current_project_id>") when ids are available
Architecture / spec / design doc → memory(action="list_docs") then memory(action="get_doc", doc_id="title or UUID")
Prior mistakes ("never do X again") → session(action="get_lessons", query="...")
User preferences / conventions / constraints → already surfaced as [PREFERENCE]; also memory(action="list_nodes", node_type="preference") or memory(action="list_nodes", node_type="constraint")
Open work / tasks / todos → memory(action="list_tasks") / memory(action="list_todos")
Active or past plans → session(action="list_plans") then session(action="get_plan", plan_id="...")
Reusable workflows / skills → skill(action="list") then skill(action="run", name="...")
Diagrams / Mermaid-style architecture maps → memory(action="create_diagram", diagram_type="flowchart|sequence|class|er|gantt|mindmap|pie|other", title="...", content="..."); diagram types are first-class and queryable with memory(action="list_diagrams")
Media assets (photos/images, video, audio, documents/PDFs) → media(action="search", query="...", content_types=["image"]), media(action="list"), or media(action="status", content_id="..."). Use image, video, audio, or document in content_types. To make a local/URL asset readable by ContextStream, use media(action="index", file_path="...", content_type="image"); friendly words like photos/images map to image, docs/PDFs/slides map to document.
Tickets / bugs / features / chores / incidents / epics → entity(kind="ticket", action="list", query={...}) then entity(kind="ticket", action="get", id="...")
Handoffs (context bundles between sessions/agents/teammates) → entity(kind="handoff", action="list") — pair with capsule(...) for the artefact bundle
Incidents (severity + status timeline) → entity(kind="incident", action="list") — distinct from EventType::Incident raw events
Releases (versioned deploys) → entity(kind="release", action="list") — changelog_doc_id links to a doc_type='release_notes' doc
Experiments / A/B tests → entity(kind="experiment", action="list")
Goals / OKRs / key results → entity(kind="goal", action="list"), then entity(kind="key_result", action="list") per goal
Sprints / iterations → entity(kind="sprint", action="list", query={"active_at": "<now>"})
Reviews (PR / code / design / security / architecture / product) → entity(kind="review", action="list")
Risks (active risk register) → entity(kind="risk", action="list") — distinct from distilled node_type='risk' summary nodes
Runbooks / ADRs / RFCs / postmortems / retros / release-notes / playbooks / PRDs / personas / glossary / SLOs / etc. → memory(action="list_docs", doc_type="runbook|adr|rfc|postmortem|retro|release_notes|playbook|prd|user_story|persona|interview|design_spec|critique|glossary|oncall_schedule|slo|q_and_a|changelog|style_guide")
"What did we do before?" (continuation work) → session(action="recall", query="...") — see the Past Sessions ladder below
Unsure which surface → memory(action="search", query="...") — hybrid across memory nodes + docs; falls back to session(action="recall", query="...") for transcript/snapshot coverage

Default assumption: if the user asks "how do we do X?", "why did we choose Y?", "what's the pattern for Z?", or "did we already decide about Q?" — the answer is likely in a doc, decision, lesson, plan, or skill, NOT in the code. Check the right knowledge surface BEFORE reading source files, re-deriving the answer, or asking the user a clarifying question.

⚠️ Don't re-ask what you just read. A common failure mode: you find a runbook/doc/ticket/decision that records a fact (which DB? which region? which env? when's the deadline? which team owns X?), then still ask the user "is this correct?" or "is this still current?". That's a wasted turn — treat surfaced knowledge as the current truth unless you have a specific reason to suspect it's stale (commit history says it changed, the user explicitly contradicts it, etc.). When in doubt about staleness, verify by reading the referenced source (git log on the file, the cited code, the linked dashboard) — not by re-asking the user.

Clarifying-question budget: before asking the user anything a project artefact could answer, do one quick pass through context()/ground() hits, runbooks, decisions, transcripts, and entity records (tickets/handoffs/releases). If after that the answer is genuinely missing or ambiguous, then ask — and make the question specific ("the runbook from 2026-04-30 says Crunchy Bridge — is that still current as of today?" beats "where is prod running?").

Before guessing, improvising, or struggling through a workflow you don't fully know:

Start with context(...) when that tool is exposed, or session(action="ground", user_message="...") when context is unavailable, and obey [GROUNDING] (prior-work anchors), [MATCHED_SKILLS], [LESSONS_WARNING], [PREFERENCE], [DECISIONS], [MEMORY], and <system-reminder> output — those are already filtered to the current task
Treat [LESSONS_WARNING] as active working instructions for the current task, not optional background context; apply them immediately and keep them in mind until the task is done
Prefer surfaced ContextStream knowledge over inventing a new workflow from memory
Prefer surfaced ContextStream knowledge over asking the user — clarifying questions are a last resort, not a first reflex

Past Sessions Are Queryable — USE THEM

Auto-Grounding (in `context()`)

When context() returns [GROUNDING], those lines are pre-ranked prior work for your current message — read them first (transcript/snapshot/doc/decision/lesson entry points). Skipping code search is often correct. For the same bundle outside context(), call session(action="ground", user_message="...").

Freshness matters: when grounding includes old decisions, transcript continuity, snapshots, plans, or tasks, refresh before using them to choose an implementation path. Recent decisions beat older decisions; superseded or stale hits are leads to verify, not assumptions to carry forward.

Transcripts for every turn of every session are captured and indexed automatically. Session snapshots bookmark turning points. Before asking the user what you did last time, or re-deriving context you built together previously, check the transcript + snapshot layer. It's fast, it's complete, and the user is paying for it.

Triggers to query past sessions:

User says "last time", "previous", "yesterday", "earlier", "we decided", "we talked about", "pick up where we left off", "what were we working on"
You have a task that's clearly a continuation (e.g. finishing a refactor that's half-done on disk)
You're about to ask a clarifying question whose answer is likely in a prior session
You're unsure whether a decision or approach has already been made

Escalation ladder — walk it in order and stop at the first step that answers the question:

session(action="recall", query="<what you're continuing>") — always the first call. Ranked fusion across transcripts, snapshots, docs, and decisions. Covers 80% of "what did we do before" questions.
memory(action="search_transcripts", query="<keyword or phrase>") — fall through when recall returns thin or off-topic results, or when you need every mention of a specific term. Full-text search across ALL saved transcripts.
memory(action="list_events", event_type="session_snapshot") — when you want the turning-point bookmarks (manual + auto pre-compaction captures). Useful for "what state were we in at the end of " questions that recall misses because the answer isn't in conversational text.
memory(action="list_transcripts", limit=10) — when you need a chronological index of recent sessions (titles, timestamps, IDs). Use when the user wants to know "when did we last work on X".
memory(action="get_transcript", transcript_id="<uuid>") — read a full past session end-to-end. Use only after the steps above pointed you at a specific transcript ID and you need the complete exchange, not snippets.
End of current session — save a bookmark for the next one: session(action="capture", event_type="session_snapshot", title="...", content="<what we did + next step>").

Never answer "I don't know what we did before" without running at least step 1, then step 2 if step 1 was thin.

Project Scope Discipline

Reuse the project_id returned by init(...) or context(...) for project-scoped writes and lookups
Reuse the workspace_id returned by init(...) or context(...) for workspace-scoped reads such as memory(action="decisions"); pass both workspace_id and project_id when both ids are available
For project-scoped memory(...), session(...), and skill(...) calls, pass explicit workspace_id and project_id instead of guessing from the folder name or title
When [PROJECT_ROUTING] appears with uncertain, ambiguous, needs_project_selection, or needs_project_setup, resolve scope before project-scoped work: choose a surfaced candidate, pass explicit workspace_id/project_id, or rerun init(folder_path="...") / context(folder_path="...")
If init(...) or context(...) does not surface a current project_id, rerun init(folder_path="...") before creating docs, skills, events, tasks, todos, or other project memory
Use target_project only after init from a multi-project parent folder

Code Health and Dependency Recommendations

When the user asks about code quality, dependency risk, circular dependencies, unused code, complexity, dashboard scans, or whether prior dashboard analysis can guide work, use the graph tool before guessing from source alone:

Dashboard freshness/cache state → graph(action="quality_freshness", project_id="...")
Trend counts over time → graph(action="quality_trends", project_id="...", limit=30)
Saved scan/run lifecycle → graph(action="quality_history", project_id="...", limit=18)
Circular dependencies → graph(action="circular_dependencies", project_id="...", limit=50)
Unused code → graph(action="unused_code", project_id="...", limit=200, element_type="Function|Type|Module|Variable")
Complexity and long functions → graph(action="complexity_metrics", project_id="...", limit=20)
Module/function dependency blast radius → graph(action="dependencies", target_type="module|function|type|variable", target_id="...")
Save a fresh dashboard baseline after scans/fixes → graph(action="quality_snapshot", project_id="...")

Use the returned recommendations field and text summary to propose next steps. If results show non-zero cycles, unused code, complexity, regressions, or missing caches, recommend a small tracked plan/ticket set before editing. If results are clean, mention the clean baseline and suggest recording/refreshing snapshots only when useful.

Response to Notices

[GROUNDING] → Read ranked prior-work hits (from context()) before broad code search; inspect source age before relying on time-sensitive decisions, transcripts, snapshots, plans, or tasks; optional one-shot: session(action="ground", user_message="...")
[GROUNDING_AVAILABLE] → Your editor may remind you when unread grounding exists; inspect freshness metadata and refresh stale hits before planning or implementation
[PROJECT_ROUTING] → Resolve ambiguous or missing project scope before project-scoped search, indexing, memory, session, skill, or capture writes; choose a candidate, pass explicit ids, or rerun init/context with folder_path
[MATCHED_SKILLS] → Run the surfaced skills before other work
[LESSONS_WARNING] → Apply the lessons shown immediately and keep them active for the current task
[PREFERENCE] → Follow user preferences exactly
[RULES_NOTICE] → Run generate_rules() to update rules
[VERSION_NOTICE] → Inform user about available updates

System Reminders

<system-reminder> tags in messages contain injected instructions from hooks. These should be followed exactly as they contain real-time context.

Search Protocol

IMPORTANT: Indexing and ingest are ALWAYS available. NEVER claim that transport mode, HTTP mode, or remote mode prevents indexing/ingest.

Check project index: project(action="index_status")
If indexed (fresh/recent/aging/stale): run search(mode="auto", query="...") immediately before local tools. Do not wait for an instantly fresh index.
If index coverage is missing or first indexing is still starting: allow background refresh up to ~20s, then search and/or use local fallback
If search returns results with a stale-index advisory, treat those results as usable for existing indexed code; refresh in background and retry only before concluding a newly edited/created symbol is absent
If search returns 0 results after a targeted retry, or you are inspecting known-new local edits, local tools are allowed

Search Mode Selection:

auto (recommended): query-aware mode selection
hybrid: mixed semantic + keyword retrieval for broad discovery
semantic: conceptual/natural-language questions ("how does auth work?")
keyword: exact text or quoted string
pattern: glob/regex queries (*.sql, foo\s+bar)
refactor: symbol usage / rename-safe lookup (UserService, snake_case)
exhaustive: all occurrences / complete match sets
team: cross-project team search

Output Format Hints:

output_format="paths" for file lists and rename targets
output_format="count" for "how many" queries

Two-Phase Search Playbook (recommended):

Discovery pass: run search(mode="auto", query="<concept + module>", output_format="paths", limit=10)
Precision pass: use symbols from pass 1 with a specific mode:
- Exact symbol/text: search(mode="keyword", query="\"my_symbol\"", include_content=true, file_types=["rs"], limit=20)
- Symbol usage/rename-safe lookup: search(mode="refactor", query="MySymbol", output_format="paths")
- Complete usage sweep: search(mode="exhaustive", query="my_symbol", file_types=["rs"])
Read locally only after narrowing: use Read/Grep on returned paths, not the full repo.

Plans and Tasks

ALWAYS use ContextStream for plans and tasks — do NOT create markdown plan files, use built-in todo/plan tools, or save plans as generic events.

Do NOT save plans this way:

session(action="capture", event_type="plan", ...)
memory(action="create_event", event_type="plan", ...)
local plan.md, .windsurf/plans, .cursor/plans, TodoWrite, todo_list, or plan_mode_respond as the durable record

Save comprehensive plans with the plan API:

session(action="capture_plan",
  title="...",
  description="scope, constraints, affected areas, acceptance criteria, verification strategy",
  goals=["clear success criterion", "..."],
  steps=[
    {"id":"plan-step-1","title":"...","order":1,"description":"scope, concrete work, files/modules if known, acceptance criteria, verification"}
  ],
  create_tasks=true)

Plan step descriptions must be detailed enough for a fresh agent to execute without re-asking: include scope, concrete work, affected files/modules if known, acceptance criteria, verification/test commands, and risks or rollback notes when relevant.

capture_plan creates one linked task per step by default. If tasks are created manually, every plan task must include:

memory(action="create_task",
  title="...",
  description="concrete work, acceptance criteria, verification",
  plan_id="<plan uuid>",
  plan_step_id="plan-step-1",
  priority="medium",
  task_status="pending")

After saving a plan, verify it is retrievable with session(action="get_plan", plan_id="<plan uuid>", include_tasks=true) or session(action="list_plans", query="...", include_tasks=true).

Memory, Docs & Todos

ALWAYS use ContextStream for memory, lessons, decisions, documents, and todos — NOT editor built-in tools, ~/.claude/.../memory/, .cursorrules, or local files. Local-file storage is invisible to the lesson/preference/skill auto-surfacing pipeline that fires on every future turn.

Lessons (mistakes, corrections, "never do X again"): session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...", severity="low|medium|high|critical", category="...")
Decisions: session(action="capture", event_type="decision", title="...", content="...")
Notes/insights: session(action="capture", event_type="note|insight", title="...", content="...")
Facts/preferences: memory(action="create_node", node_type="fact|preference", title="...", content="...")
Documents: memory(action="create_doc", title="...", content="...", doc_type="spec|general")
Todos: memory(action="create_todo", title="...", todo_priority="high|medium|low") Do NOT use create_memory, TodoWrite, todo_list, or local file writes for persistence.

Skills (IMPORTANT — Do Not Ignore Matched Skills)

When context() returns [MATCHED_SKILLS], you MUST run the listed skills via skill(action="run", name="...").

Skills marked ⚡ (high-priority, priority ≥ 80) are mandatory — run them immediately before other work
Skills marked ▶ (recommended, priority ≥ 60) should be run unless clearly irrelevant
Skills marked ○ (available) are optional but often helpful

Reusable instruction + action bundles that persist across projects and sessions:

Browse: skill(action="list") or skill(action="list", scope="team")
Create: skill(action="create", name="...", instruction_body="...", trigger_patterns=[...])
Update: skill(action="update", name="...", instruction_body="...", change_summary="...") (name or skill_id)
Run: skill(action="run", name="...") — executes the skill's action pipeline
Import: skill(action="import", file_path="CLAUDE.md", format="auto") — imports from any rules file
Skills auto-activate when their trigger keywords match the user's message. The context() response surfaces them.

Code Search

ALWAYS use ContextStream search() before Glob, Grep, Read, SemanticSearch, code_search, grep_search, or find_by_name. Do NOT launch Task/explore subagents for code search — use search(mode="auto", query="...") directly. ContextStream search results contain real file paths, line numbers, and code content — they ARE code results. NEVER dismiss ContextStream results as "non-code" — use the returned file paths to read_file the relevant code. Use search(include_content=true) to get inline code snippets in results.

Context Pressure

When context() returns context_pressure.level: "high":

Save a session snapshot before compaction
session(action="capture", event_type="session_snapshot", title="...", content="...")
After compaction: init(folder_path="...", is_post_compact=true) to restore snapshots/transcripts
If init restore is thin: session(action="restore_context", trigger="manual_post_compact", include_durable_context=true) then session(action="recall", query="what were we doing before compaction")

IMPORTANT: No Hooks Available

This editor does NOT have hooks to enforce ContextStream behavior. You MUST follow these rules manually - there is no automatic enforcement.

ContextStream Knowledge First

Before guessing or struggling through an unfamiliar workflow, check ContextStream first.

Start with context(...) when that tool is exposed, or session(action="ground", user_message="...") when context is unavailable, and follow [MATCHED_SKILLS], [LESSONS_WARNING], [PREFERENCE], and <system-reminder> output
Treat [LESSONS_WARNING] as active working instructions for the current task, not optional background context
If the task is unfamiliar, process-heavy, or likely documented already, inspect skill(action="list"), memory(action="list_docs"), session(action="get_lessons"), or memory(action="decisions", workspace_id="<current_workspace_id>", project_id="<current_project_id>") when ids are available before trial-and-error
If context() or session(action="ground", ...) returns [MATCHED_SKILLS], run the listed skills before other work

SESSION START PROTOCOL

On EVERY new session, you MUST:

Call init(folder_path="<project_path>") FIRST
- This triggers project indexing
- Check response for indexing_status
- If indexed coverage already exists, search immediately even while refresh continues; wait only when no usable index exists yet
Generate a unique session_id (e.g., "session-" + timestamp or a UUID)
- Use this SAME session_id for ALL context() calls in this conversation
Call context(user_message="<first_message>", session_id="<id>") if available; otherwise call session(action="ground", user_message="<first_message>", session_id="<id>")
- Gets task-specific rules, lessons, and preferences
- Check for [LESSONS_WARNING], [PREFERENCE], [RULES_NOTICE]
- If [LESSONS_WARNING] appears, treat those lessons as mandatory instructions for the task until it is finished
Default behavior: call context(...) first on each message when available; otherwise call session(action="ground", user_message="..."). Narrow bypass is allowed only for immediate read-only ContextStream calls when previous context is still fresh and no state-changing tool has run.
Instruction alignment (if tool is exposed): call instruct(action="get", session_id="<id>") before context(...) each turn, and instruct(action="ack", session_id="<id>", ids=[...]) after using entries.

TRANSCRIPT SAVING (OPTIONAL)

Transcripts are OFF by default.

Enable for this chat:

context(user_message="<user's message>", save_exchange=true, session_id="<session-id>")

Disable for this chat:

context(user_message="<user's message>", save_exchange=false, session_id="<session-id>")

Default policy via MCP config env:

CONTEXTSTREAM_TRANSCRIPTS_ENABLED="true|false"
CONTEXTSTREAM_HOOK_TRANSCRIPTS_ENABLED="true|false"

Session ID Guidelines:

Generate ONCE at the start of the conversation
Use a unique identifier (UUID or timestamp-based)
Keep the SAME session_id for ALL context() calls
Different sessions = different transcript preference state

FILE INDEXING (CRITICAL)

There is NO automatic file indexing in this editor. You MUST manage indexing manually:

IMPORTANT: Indexing and ingest are ALWAYS available. NEVER claim that transport mode, HTTP mode, or remote mode prevents indexing/ingest operations. Both project(action="index") and project(action="ingest_local") work in all configurations.

After Creating/Editing Files:

project(action="index")

If folder context is active, this resolves the current repo and uses the local ingest path automatically.

To Target A Specific Folder Or Recover From Stale Scope:

project(action="ingest_local", path="<project_folder>")

Signs You Need to Re-index:

Search doesn't find code you just wrote
Search returns old versions of functions
New files don't appear in search results

SEARCH-FIRST (No PreToolUse Hook)

There is NO hook to redirect local tools. You MUST self-enforce:

Before Broad Local Discovery, Check Index Status:

project(action="index_status")

Search Protocol:

IF indexed (fresh/recent/aging/stale): run search(mode="auto", query="...") immediately before local tools. Do not wait for an instantly fresh index.
IF no usable index exists yet: allow background indexing up to ~20s, then retry search(mode="auto", ...) and/or use local fallback
IF search returns results with a stale-index advisory: use those results for existing indexed code; refresh in background and retry only before concluding a newly edited/created symbol is absent
IF search returns 0 results after a targeted retry, or you are inspecting known-new local edits: local tools are allowed

Choose Search Mode Intelligently:

auto (recommended): query-aware mode selection
hybrid: mixed semantic + keyword retrieval for broad discovery
semantic: conceptual questions ("how does X work?")
keyword: exact text / quoted string
pattern: glob or regex (*.ts, foo\s+bar)
refactor: symbol usage / rename-safe lookup
exhaustive: all occurrences / complete match coverage
team: cross-project team search

Output Format Hints:

Use output_format="paths" for file listings and rename targets
Use output_format="count" for "how many" queries

Two-Phase Search Pattern (for precision):

Pass 1 (discovery): search(mode="auto", query="<concept + module>", output_format="paths", limit=10)
Pass 2 (precision): use one of:
- exact text/symbol: search(mode="keyword", query="\"exact_text\"", include_content=true)
- symbol usage: search(mode="refactor", query="SymbolName", output_format="paths")
- all occurrences: search(mode="exhaustive", query="symbol_or_text")
Then use local Read/Grep only on paths returned by ContextStream.

When Local Tools Are OK:

No usable index exists after the initial grace window (~20s default, configurable)
ContextStream search still returns 0 results or errors after a targeted retry
You are inspecting known-new or recently edited files that the index may not contain yet
User explicitly requests local tools

CONTEXT COMPACTION (No PreCompact Hook)

There is NO automatic state saving before compaction. You MUST save state manually when the conversation gets long:

When to Save State:

After completing a major task
Before the conversation might be compacted
If context() returns context_pressure.level: "high"

How to Save State:

session(action="capture", event_type="session_snapshot",
  title="Session checkpoint",
  content="{ \"summary\": \"what we did\", \"active_files\": [...], \"next_steps\": [...] }")

After Compaction (if context seems lost):

init(folder_path="...", is_post_compact=true)
session(action="restore_context", trigger="manual_post_compact", include_durable_context=true)
session(action="recall", query="what were we doing before compaction")

PLANS & TASKS (CRITICAL)

NEVER create markdown plan files — they vanish across sessions and are not searchable. NEVER use built-in todo/plan tools (e.g., TodoWrite, todo_list, plan_mode_respond) — use ContextStream instead. NEVER save plans as generic events — do not use session(action="capture", event_type="plan") or memory(action="create_event", event_type="plan").

ALWAYS use ContextStream for planning:

session(action="capture_plan",
  title="...",
  description="scope, constraints, affected areas, acceptance criteria, verification strategy",
  goals=["..."],
  steps=[{"id":"plan-step-1","title":"...","order":1,"description":"scope, concrete work, files/modules if known, acceptance criteria, verification"}],
  create_tasks=true)
memory(action="create_task",
  title="...",
  description="concrete work, acceptance criteria, verification",
  plan_id="<plan uuid>",
  plan_step_id="plan-step-1",
  priority="medium",
  task_status="pending")

Plans and tasks in ContextStream persist across sessions, are searchable, and auto-surface in context.

MEMORY & DOCS (CRITICAL)

NEVER use built-in memory tools (e.g., create_memory) — use ContextStream instead. NEVER write docs/specs/notes to local files — use ContextStream docs instead.

ALWAYS use ContextStream for persistence:

session(action="capture", event_type="decision|insight|operation|uncategorized", title="...", content="...")
memory(action="create_node", node_type="fact|preference", title="...", content="...")
memory(action="create_doc", title="...", content="...", doc_type="spec|general")
memory(action="create_todo", title="...", todo_priority="high|medium|low")

ContextStream memory, docs, and todos persist across sessions, are searchable, and auto-surface in context.

VERSION UPDATES

Check for updates periodically using help(action="version").

If the response includes [VERSION_NOTICE] or [VERSION_CRITICAL], tell the user about the available update.

Update Commands:

# macOS/Linux
curl -fsSL https://contextstream.io/scripts/setup.sh | bash
# npm
npm install -g @contextstream/mcp-server@latest

VS Code Copilot Notes

Keep this file concise; put detailed workflows in .github/skills/contextstream-workflow/SKILL.md
Use ContextStream plans/tasks as the persistent record of work
Save plans with session(action="capture_plan", ..., create_tasks=true), not generic plan events; linked tasks need plan_id, plan_step_id, detailed descriptions, priority, and status
Before code discovery, use search(mode="auto", query="...")

Repository README

Describes CortexPrism/cortex as a whole, which may contain artifacts other than this one. Where this artifact had no useful description of its own, its summary was taken from here.

CortexPrism

Star History

The open-source AI agent operating system — autonomous agents with memory, tools, a web UI, and layered security, powered by Deno.

CortexPrism is a self-hosted, open-source AI agent operating system — an autonomous agent runtime that turns any LLM into a capable digital agent. It provides persistent memory, a rich tool ecosystem, sandboxed code execution, multi-agent orchestration, a full-featured web UI, and enterprise-grade security — all running locally on your machine or server.

Works with 30 LLM providers out of the box (Anthropic, OpenAI, Gemini, Groq, Ollama, and more)
Ships as a single Deno binary — no Docker required to get started
100% open source — Apache 2.0 licensed, no telemetry, data stays on your machine

Features
Requirements
Quick Start
CLI Reference
Configuration
Web UI
Security Model
Plugin System
Architecture
Contributing
License

Features

AI Providers & Model Routing

30 LLM providers — Anthropic Claude, OpenAI GPT, Google Gemini, Mistral, Groq, DeepSeek, OpenRouter, xAI Grok, Together AI, AWS Bedrock, Cohere, Ollama (local models), Cerebras, Fireworks, Perplexity, NVIDIA NIM, Moonshot (Kimi), Novita AI, LM Studio, LiteLLM, Hugging Face, Alibaba (Qwen), Venice AI, Kilo AI, DeepInfra, Hyperbolic, MiniMax, Zhipu (GLM), Replicate, Cloudflare Workers AI
Multimodal input — upload images and documents; native vision support for Anthropic and Google Gemini; PDF text auto-extracted for all providers
Model Quartermaster (MQM) — intelligent model selection that learns which model performs best for each task type using a 6-signal prediction engine with adaptive EMA learning and three arbiter strategies (conservative / balanced / aggressive)
Model router — RouteLLM-style cascade (cheapest-first escalation) and threshold (prompt-scoring) routing strategies

Agent Capabilities

Interactive streaming chat — CLI and Web UI with real-time streaming, session persistence, and session resume
Tool use with approval gates — every tool call is reviewed by the security policy before execution; agents can request human approval for sensitive operations
Sub-agent orchestration — agents can spawn 11 specialized child agents (Explorer, General, Planner, Coder, Researcher, Security, Debugger, Architect, DevOps, Data Analyst, UI/UX Designer) for parallel and delegated work
Per-turn reflection — LLM self-assessment of confidence and quality after each response; meta- pattern consolidation over time
Voice pipeline — speech-to-text (OpenAI Whisper), text-to-speech (OpenAI TTS / ElevenLabs), energy-based VAD, real-time audio streaming over WebSocket
Computer use — GUI automation via virtual displays (Xvfb) with mouse, keyboard, and screenshot actions; Docker-isolated or native runtime
Code intelligence — tree-sitter WASM code indexing across 14+ languages; call graph traversal, impact analysis, architecture extraction, and symbol search
Browser automation — headless Playwright-powered browser for web navigation, interaction, screenshots, and accessibility snapshots

Memory System

5-tier memory — episodic (FTS5 full-text search), semantic (vector embeddings), procedural (skills), graph (knowledge graph), and reflection (learned patterns) with multi-strategy retrieval and decay scoring
Heuristic self-learning — AI-driven memory improvement: access-tracking importance boosting, decay-slowing for frequent memories, co-occurrence graph relations, and 12-rule auto-categorization
Hybrid search — keyword (FTS5 BM25) + vector (cosine similarity) search with time-decay scoring
Automatic memory injection — relevant memories are injected into each turn's system prompt
Memory search CLI — keyword, semantic, and hybrid search from the terminal
Memory health dashboard — aggregated metrics for active/stale counts, decay, importance, access frequency, and graph stats

Skills System

Self-learning skills — the agent automatically extracts reusable procedural patterns from successful tool-call sequences and stores them as versioned, quality-scored skills
Skill lifecycle — 6-state lifecycle (candidate → verified → released → degraded → deprecated → archived) with automatic health monitoring and staleness detection
Embedding-based retrieval — skills are matched to user queries via cosine similarity over precomputed embeddings, with lexical fallback for cold starts
Skill deduplication — similar skills are automatically detected and merged, preserving steps and bumping versions; LLM-extracted skills are deduplicated on creation
Dependency tracking — skills can declare depends_on and conflicts_with relationships; deletion is blocked if other skills depend on the target
Trust tiering — 4-tier system (1=LLM-extracted, 4=built-in vetted) gates agent skill exposure
Health system — composite quality scores from utility, freshness, redundancy, and failure risk; automatic maintenance deprecates stale/low-quality skills
Tool-accessible — load_skill, skill_read, skill_write (create/update/delete/merge/promote/deprecate)
Web UI & REST API — full skill library management with lifecycle badges, trust stars, dependency graphs, health reports, and bulk operations
Skill SDK — define skills as TypeScript modules (src/skills/builtin/) or markdown files in .cortex/skills/<name>/SKILL.md with YAML frontmatter

See docs/SKILLS.md for the full reference.

Code Intelligence (Codegraph)

Multi-language parsing — tree-sitter WASM parser for 14+ languages (TS, JS, Python, Go, Rust, Java, Kotlin, C, C++, Ruby, PHP, Swift, Lua, Bash)
Call graph resolution — 6-strategy call target resolution with import analysis across all supported languages
Code graph storage — 14 node labels (CodeProject, CodeFile, CodeFunction, CodeClass, etc.), 18 edge types (CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS, HTTP_CALLS, DECORATES, etc.)
6 agent tools — code_index, code_search_symbol, code_trace_path, code_get_architecture, code_analyze_impact, code_list_projects
Web UI — D3.js force-directed dependency graph with symbol search, impact analysis, and path tracing
Incremental sync — file-hash-based change detection with chunked bulk insert and BFS-batched queries

Built-in Tools

Category	Tools
File system	read, write, edit, patch, delete, rename, copy, move, list, tree, info, search, glob, undo/redo
Shell	execute shell commands (sandboxed through policy validator)
Web	web_search, web_fetch, web_crawl, docs_search (Context7 docs), firecrawl (web scraping)
Code execution	sandboxed Docker/gVisor containers with resource limits; LLM auto-fix loop
Browser	navigate, click, type, screenshot, snapshot, evaluate, wait (Playwright headless automation)
GitHub	PR creation/listing, issue tracking, repo browsing, git push
Git workspace	status, commit, push, pull, branch, clone
Voice	speak, listen (STT/TTS agent tools)
Data & Util	memory_note, memory_search, db_query, structured_extract, json_query, regex_utils, code_snippet
Environment	env_manager (get/set variables), schedule (cron-based job scheduling)
Sandbox	environment snapshots, workspace snapshots, dev env as code, bug reproduction studio
Image & Vision	image_analyze (multimodal image analysis via 18+ LLM providers)
Sub-agents	spawn typed child agents for parallel and delegated tasks
Skills	load_skill, skill_read, skill_write (create/update/delete/merge/promote/deprecate)
Dashboard	dashboard_manage — CRUD operations on dashboard widgets
Nodes	node_dispatch — dispatch tasks to remote distributed nodes
Code Intelligence	code_index, code_search_symbol, code_trace_path, code_analyze_impact, code_get_architecture
Computer Use	screenshot, left_click, type, key, scroll, mouse_move, drag (GUI automation via Xvfb + xdotool)

Web UI & REST API

Built-in HTTP server — cortex server start starts a WebSocket-powered chat UI on port 3000
Pages: Chat, Dashboard, Editor, VCS, Sessions, Memory, Skills, Soul, Agents, Services, Nodes, Daemons, Automation, Channels, Tools, MCP, Codegraph, Policies, Vault, Settings, Quartermaster, Extensions, Analytics, Lens (Activity), Workflows, Eval Runner, Computer Use, Remote Agents, Sandbox, Prompt Lab, PKM, Metacognition, Voice, Tunnel, Projects, Teams, Users
File upload — drag-and-drop or click to attach PDFs, images, and documents in chat
REST API — full HTTP API for sessions, memory, jobs, git, GitHub, and code execution
Session persistence — page refresh resumes the active session (full history preserved)

Security (Parallax Model + LLM Supervisor)

Policy validator — every tool call is evaluated against regex allow/deny rules before execution
Dynamic tool permission grant — per-task permission evaluation with risk profiles and guardrails (readOnly, restrictedPaths, allowedDomains, requireConfirmation)
Tool approval workflow — structured approval pipeline with auto-approve thresholds, webhook notifications, and 5-minute timeouts
LLM supervisor — sensitive data access (memory, databases, screenshots) requires approval from a fast LLM supervisor model (Gemini 2.0 Flash, GPT-4o Mini) with decision caching and human escalation for uncertain cases
Data classification — automatic sensitivity detection (SECRET/SENSITIVE/NORMAL/PUBLIC) based on pattern matching (passwords, API keys, PII, confidential markers); all existing data backfilled on first run
DLP Guard — 22-scanner data loss prevention scanning all agent outputs for sensitive data (API keys, credentials, PII, PHI, PCI); supports monitor/redact/block action levels
AI Guardrails — pluggable content safety middleware with 5 built-in classifiers: prompt injection (10 patterns), PII leakage, harmful code, excessive length, and shell injection
Session isolation — multi-tenant data isolation with path-based and environment-variable gating across strict, permissive, and shared modes
Human approval flows — CLI color-coded prompts and Web UI modal for sensitive access requests, with AI supervisor reasoning and sample data preview
Temporary grants — approved access cached per session to prevent approval fatigue while maintaining security
AES-256-GCM vault — encrypted credential storage with PBKDF2 key derivation
Default deny rules — ships with protection against rm -rf /, fork bombs, direct disk writes
Activity — full audit log of all sessions, tool calls, LLM calls, policy decisions, and security approvals with cost tracking See docs/SECURITY_SUPERVISOR.md for the full architecture.

Computer Use (GUI Automation)

Virtual display — X11 virtual framebuffer (Xvfb) lifecycle management with multi-display support
Mouse control — coordinate-based movement, left/right/middle clicks, double/triple clicks, drag
Keyboard control — text typing with configurable delays, key combinations, key holding
Screenshot capture — PNG/JPEG output via scrot, ImageMagick, or xwd with automatic fallback
15 agent actions — screenshot, click, type, key, scroll, wait, mouse_move, drag, and more
Security — all actions gated through policy validator with user approval; sensitive data auto-blocked
Docker support — pre-built Ubuntu 22.04 image with XFCE, Firefox, Chromium, LibreOffice
Requirements — xvfb, xdotool, scrot (Linux-only)

See docs/computer-use/README.md for the full guide.

Ops & Extensibility

Multi-user collaboration — users, teams, API tokens with SHA-256 hashing, resource scoping, federation between instances
Distributed swarm — cross-instance agent coordination via A2A protocol with fleet topology, resource aggregation, and directive dispatch
Scheduled jobs — SQLite-persisted cron with automatic retry
Daemon supervisor — manages validator, executor, and scheduler processes with exponential backoff restart
Plugin system — WASM and Deno module plugins with sandboxed permissions
MCP Gateway — enterprise MCP server management with rate limiting, health checks, audit logging
A2A Protocol Bridge — Google Agent2Agent (A2A) v1.0 protocol for cross-framework agent collaboration with JSON-RPC 2.0 server/client, SSE streaming, and tool wrapping
Memori Checkpointing — persistent agent state serialization and restore for survival across restarts, crashes, and context window resets
Supply chain integrity — plugin verification with SHA-256 hash checking, signature verification, author reputation scoring, and malware pattern scanning
Dependency guardian — continuous CVE monitoring, license enforcement, and remediation suggestions across 6 package ecosystems
AgentLint — automated auditing of agent configs, tools, plugins, and prompts with 33+ checks
Auto-update — cortex self update supports source mode and signed binary mode with SHA-256 and optional GPG verification
Desktop app — Tauri-based desktop wrapper (macOS, Windows, Linux)

Requirements

Requirement	Notes
Deno 2.x	Required — the installer handles this automatically
Docker	Optional — needed for sandboxed code execution; subprocess fallback is available
macOS, Linux, or Windows	All platforms supported

Quick Start

Option 1: One-line installer (recommended)

macOS / Linux:

curl -fsSL https://cortexprism.io/install.sh | bash

Windows (PowerShell):

irm https://cortexprism.io/install.ps1 | iex

The installer: checks for / installs Deno, clones Cortex to ~/.cortex, creates the cortex CLI alias, and runs database migrations. After install, run cortex setup to configure your first LLM provider.

Option 2: Manual clone

git clone https://github.com/CortexPrism/cortex.git ~/.cortex
cd ~/.cortex
deno task migrate
deno run --allow-all src/main.ts setup

Add cortex to your PATH by appending to your shell profile:

echo 'alias cortex="deno run --allow-all ~/.cortex/src/main.ts"' >> ~/.bashrc
source ~/.bashrc

Option 3: Pre-compiled binary

Download the latest binary from the Releases page. All binaries include SHA-256 checksums and optional GPG signatures.

First run

cortex setup        # Interactive setup wizard — choose provider, enter API key
cortex agent chat         # Start your first chat session
cortex server start        # Open the Web UI at http://127.0.0.1:3000

CLI Reference

cortex <command>

Commands:
  agent             Agent commands (chat, exec, tui, sessions, eval, reflect, lint, voice)
  setup             Re-run the setup wizard
  server start      Start the HTTP + WebSocket server with Web UI
  daemon            Manage background processes (validator, executor, scheduler)
  sandbox           Code execution in sandboxed environment
  memory            Search and manage memory
  jobs              Manage scheduled jobs
  vault             Encrypted credential vault (store / get / list / delete)
  policy            Security policy rules (list / add / remove / check)
  db migrate        Initialise or migrate all databases
  self update       Check for and apply updates
  config            View and edit configuration
  git               Git workspace operations
  github            GitHub integration (PRs, issues, repos)
  mqm               Model Quartermaster stats and configuration
  qm                Quartermaster tool orchestration stats
  models            List and configure LLM models
  soul              Manage agent identity and personality templates
  plugins           Install and manage plugins
  marketplace       Browse and install from the plugin/agent marketplace
  log               View and manage logging configuration
  service           Manage micro-services (start, stop, install, uninstall)
  node              Manage distributed nodes
  hooks             Manage pipeline hooks
  triggers          Manage event triggers
  channels          Manage channel adapters (Discord, etc.)
  mcp               MCP server commands (serve, stdio, chrome, a2a)
  desktop           Desktop automation
  workflow          Workflow engine operations
  projects          Project management
  swarm             Distributed agent swarm (init, nodes, topology, report)
  login             Authenticate with username/password or API token
  logout            End current authenticated session
  whoami            Show current authenticated user
  users             User management (list, create, disable, enable)
  teams             Team management (list, create)
  compliance        Compliance policy management
  debug             Debug utilities
  memori            Memori checkpointing and persistence
  import            Tool output import
  tunnel            Tunnel management
  run               Execute a task via CLI
  update            Update CortexPrism
  migrate           Run pending database migrations

`cortex agent`

cortex agent chat                          # Start a new chat session
cortex agent chat --model gpt-4o           # Override the active model
cortex agent chat --resume sess_abc123     # Resume an existing session
cortex agent chat -s sess_abc123           # Resume (short flag)
cortex agent chat --no-stream              # Disable streaming output
cortex agent exec <task>                   # Execute a one-shot agent task
cortex agent tui                           # Launch terminal UI
cortex agent sessions                      # List recent chat sessions
cortex agent eval <suite>                  # Run an evaluation suite
cortex agent reflect                       # Inspect and consolidate reflection patterns
cortex agent lint                          # Run AgentLint auditing
cortex agent voice                         # Voice mode management

Slash commands inside chat:

/exit   Quit
/help   Show available commands
/clear  Clear the screen

`cortex sandbox run <file>`

Execute a code file in an isolated sandbox with optional LLM auto-fix:

cortex sandbox run script.py                    # Run in Docker sandbox (auto-detect language)
cortex sandbox run script.py --no-sandbox       # Run as direct subprocess
cortex sandbox run script.py --fix              # Enable LLM auto-fix loop on failure
cortex sandbox run script.py --fix --max-fix 6  # Up to 6 fix attempts

Supported languages: python, javascript, typescript, bash, ruby, go, rust

`cortex server start`

Start the built-in HTTP + WebSocket server:

cortex server start                         # http://127.0.0.1:3000 (foreground)
cortex server start --port 8080 --host 0.0.0.0
cortex server start -d                      # Run in the background (daemon mode)
cortex server start -d -r                   # Restart background server
cortex server start -s                      # Stop background server
cortex daemon stop                          # Stop server + all daemons
cortex daemon stop --server-only
cortex daemon stop --daemon-only

`cortex daemon`

cortex daemon start                  # Start supervisor in background (auto-restart on crash)
cortex daemon stop
cortex daemon restart
cortex daemon run                    # Run supervisor in foreground (for systemd / tmux)
cortex daemon status

Four daemon processes: Validator (policy enforcement), Executor (tool execution), Scheduler (cron jobs and memory consolidation), Supervisor (LLM security supervisor). The daemon supervisor auto-restarts any crashed daemon with exponential backoff.

`cortex git`

Full git workspace management for agent and global workspaces:

cortex git status [--agent <id>]
cortex git log [--agent <id>] [--limit 20]
cortex git diff [--agent <id>] [--stat] [--file <path>]
cortex git add <file...> [--agent <id>]
cortex git add --all [--agent <id>]
cortex git commit <message> [--agent <id>]
cortex git push [--agent <id>] [--remote origin] [--branch <name>]
cortex git pull [--agent <id>]
cortex git clone <url> <dest> [--branch <name>]
cortex git branch [--agent <id>]
cortex git branch --create <name> [--agent <id>]
cortex git branch --checkout <name> [--agent <id>]
cortex git remote --add <name> --url <url> [--agent <id>]

`cortex github`

GitHub integration — requires GITHUB_TOKEN env var, githubToken in config, or vault entry github_token:

cortex github pr list <repo> [--state open] [--limit 10]
cortex github pr get <repo> <number>
cortex github pr create <repo> <title> <head> <base> [--body "..."] [--draft]
cortex github pr merge <repo> <number> [--method merge|squash|rebase]
cortex github pr close <repo> <number>
cortex github issue list <repo> [--state open] [--limit 10] [--labels a,b]
cortex github issue create <repo> <title> [--body "..."] [--labels a,b]
cortex github issue close <repo> <number>
cortex github repo list [--type all|owner|public|private] [--limit 20]
cortex github repo get <repo>
cortex github repo branches <repo> [--limit 30]
cortex github token

`cortex agent sessions`

cortex agent sessions                      # List recent sessions
cortex agent sessions --limit 20           # Limit results
cortex agent sessions --agent <id>         # Filter by agent

`cortex memory`

cortex memory search "sqlite"           # Keyword + vector hybrid search
cortex memory search "sqlite" --type semantic # Vector only
cortex memory add "CortexPrism uses SQLite WAL mode"
cortex memory health                     # Memory health stats
cortex memory heuristics                 # Trigger heuristic learning

`cortex vault`

AES-256-GCM encrypted credential storage:

export CORTEX_VAULT_KEY="your-passphrase"

cortex vault store "openai-key" --service openai  # Prompts for the value
cortex vault get "openai-key"
cortex vault list
cortex vault delete "openai-key"

The passphrase is never stored — only held in the environment variable at runtime (PBKDF2 key derivation, 100k iterations, SHA-256).

`cortex policy`

cortex policy list
cortex policy add "curl.*evil\.com" --kind shell --effect deny --reason "Blocked domain"
cortex policy check shell "rm -rf /etc"
cortex policy remove pol_abc123

Default deny rules (seeded on first migrate):

rm\s+-rf\s+/ — recursive root delete
:\(\)\{.*\} — fork bomb patterns
dd\s+if=.*of=/dev/ — direct disk writes
chmod\s+777\s+/ — world-write on root

`cortex self update`

cortex self update              # Check for updates and apply
cortex self update --check      # Dry-run — show available versions without applying
cortex self update --channel pre-release # Include pre-release versions
cortex self update --rollback   # Revert to previous version
cortex self update --status     # Show current and latest version
cortex self update --force      # Bypass dirty working tree check (source mode)

Supports source mode (git pull) and binary mode (download + SHA-256 + optional GPG verification).

`cortex mqm`

cortex mqm stats            # Performance statistics per model
cortex mqm decisions        # Recent routing decisions
cortex mqm weights          # Current signal weights
cortex mqm accuracy         # Prediction accuracy metrics

`cortex agent voice`

cortex agent voice enable            # Enable voice mode
cortex agent voice disable
cortex agent voice status
cortex agent voice set-voice <voice-id>

`cortex log`

cortex log show                          # Print last 100 log entries
cortex log show --lines=200 --level=warn # Filter by level
cortex log tail                          # Live tail (Ctrl+C to stop)
cortex log tail --level=debug            # Tail with filters
cortex log clear                         # Truncate the log file
cortex log path                          # Print log file path
cortex log set-level info                # Update log level in config
cortex log status                        # Show current logging config

`cortex plugins`

cortex plugins install <source>               # Install from URL, local file, or marketplace
cortex plugins list                           # List installed plugins
cortex plugins enable <name>                  # Enable a plugin
cortex plugins disable <name>                 # Disable a plugin
cortex plugins remove <name>                  # Remove a plugin
cortex plugins update <name>                  # Update a plugin
cortex plugins update --all                   # Update all plugins
cortex plugins verify <name>                  # Verify integrity hash
cortex plugins permissions <name>             # Inspect plugin permissions

`cortex agent eval`

cortex agent eval list                        # List available evaluation suites
cortex agent eval run <suite>                 # Run an evaluation suite
cortex agent eval run <suite> --save-baseline # Save results as baseline
cortex agent eval run <suite> --baseline <name> # Compare against a baseline
cortex agent eval baselines                   # List saved baselines

`cortex eval memory`

cortex eval memory list                       # List memory evaluation suites
cortex eval memory run <suite>                # Run a memory evaluation

`cortex node`

cortex node register <name> [--tier root|sudo|unprivileged]   # Register a distributed node
cortex node list                                               # List all nodes
cortex node show <id>                                          # Show node details + metrics
cortex node deregister <id>                                    # Remove a node
cortex node rekey <id>                                         # Rotate node auth token
cortex node connect <endpoint> [--tier <tier>]                 # Connect as a Cortex Node

`cortex mcp`

cortex mcp serve                              # Start MCP server in HTTP mode
cortex mcp stdio                              # Start MCP server over stdio (Claude Desktop)
cortex mcp chrome                             # Start Chrome Bridge MCP
cortex mcp a2a                                # Manage A2A protocol agents
cortex mcp a2a remote                         # List configured remote A2A agents

`cortex workflow`

cortex workflow list                          # List defined workflows
cortex workflow run <name>                    # Execute a workflow
cortex workflow approve <runId>               # Approve a pending workflow step

`cortex triggers`

cortex triggers list                          # List event triggers
cortex triggers add <type> [--pattern <glob>] # Add a file-watch or cron trigger
cortex triggers remove <id>                   # Remove a trigger
cortex triggers install-hooks                 # Install git post-receive/commit hooks
cortex triggers uninstall-hooks               # Remove git hooks

`cortex hooks`

cortex hooks list                             # List pipeline hooks
cortex hooks disable <name>                   # Disable a hook
cortex hooks init                             # Initialize hook config

`cortex channels`

cortex channels list                          # List configured channels
cortex channels start <name>                  # Start a channel adapter
cortex channels stop <name>                   # Stop a channel adapter

`cortex desktop`

cortex desktop screenshot                     # Capture a screenshot
cortex desktop click <x> <y>                  # Click at coordinates
cortex desktop type <text>                    # Type text
cortex desktop keypress <key>                 # Press a key or key combination
cortex desktop clipboard get|set <text>       # Clipboard operations
cortex desktop dockerfile                     # Generate Docker desktop container config
cortex desktop entrypoint                     # Generate desktop automation entrypoint

`cortex projects`

cortex projects list                          # List workspace projects
cortex projects create <name>                 # Create a new project
cortex projects delete <name>                 # Delete a project

Configuration

Config file: ~/.cortex/config.json (created by cortex setup)

{
  "version": 1,
  "defaultProvider": "anthropic",
  "providers": {
    "anthropic": { "kind": "anthropic", "model": "claude-sonnet-4-5", "apiKey": "sk-..." },
    "openai": { "kind": "openai", "model": "gpt-4o", "apiKey": "sk-..." },
    "google": { "kind": "google", "model": "gemini-2.0-flash", "apiKey": "..." },
    "mistral": { "kind": "mistral", "model": "mistral-large-latest", "apiKey": "..." },
    "groq": { "kind": "groq", "model": "llama-3.3-70b-versatile", "apiKey": "gsk_..." },
    "deepseek": { "kind": "deepseek", "model": "deepseek-chat", "apiKey": "sk-..." },
    "openrouter": { "kind": "openrouter", "model": "openai/gpt-4o", "apiKey": "..." },
    "xai": { "kind": "xai", "model": "grok-2-latest", "apiKey": "..." },
    "together": {
      "kind": "together",
      "model": "meta-llama/Llama-3.3-70B-Instruct-Turbo",
      "apiKey": "..."
    },
    "bedrock": { "kind": "bedrock", "model": "us.amazon.nova-pro-v1:0", "region": "us-east-1" },
    "cohere": { "kind": "cohere", "model": "command-r-plus", "apiKey": "..." },
    "ollama": { "kind": "ollama", "model": "llama3.2", "baseUrl": "http://localhost:11434" }
  },
  "agent": { "name": "Cortex", "maxTurns": 8, "streamOutput": true },
  "router": {
    "enabled": false,
    "strategy": "cascade",
    "confidenceThreshold": 0.7
  },
  "modelSelection": {
    "enabled": true,
    "mode": "balanced",
    "observeThreshold": 50
  },
  "update": {
    "channel": "stable",
    "checkOnStartup": true
  },
  "voice": {
    "enabled": false,
    "provider": "openai",
    "defaultVoice": "alloy",
    "autoTTS": false
  },
  "logging": {
    "level": "info",
    "fileEnabled": true
  },
  "webAuth": {
    "requireAuth": false
  }
}

Environment Variables

Variable	Purpose
`CORTEX_DATA_DIR`	Override data directory (default: `~/.cortex/data/`)
`CORTEX_CONFIG_DIR`	Override config directory (default: `~/.cortex/`)
`CORTEX_VAULT_KEY`	Vault decryption passphrase (required to use `cortex vault`)
`CORTEX_LOG_LEVEL`	Override log level (trace, debug, info, warn, error, silent)
`GITHUB_TOKEN`	GitHub personal access token for the `github` command
`OPENAI_API_KEY`	OpenAI API key (alternative to config file)

Web UI

Start with cortex server start and open http://127.0.0.1:3000.

Section	Page	Description
Core	Chat	WebSocket streaming chat with file upload (PDF, images, documents)
Core	Dashboard	Widget-based overview with KPI cards, daemon status, system resources
Core	Sessions	Browse, search, archive, and resume past chat sessions
Core	Projects	Workspace-scoped project management with CRUD operations
Intelligence	Memory	5-tier memory search with graph browser, reflections, and health
Intelligence	Skills	Skill library with lifecycle badges, trust stars, and dependency graphs
Intelligence	Soul	Edit agent identity / system prompt (SOUL.md, USER.md, MEMORY.md)
Development	Editor	Full file editor powered by CodeMirror with git integration
Development	Code Runner	Sandboxed code execution (Docker/gVisor) with language selection
Development	Version Control	Git workspace — status, stage, commit, diff, push, pull, branch
Infrastructure	Agents	Agent registry with sub-agent types, process management, CRUD
Infrastructure	Services	Micro-service lifecycle with start/stop, health pings, auto-restart
Infrastructure	Nodes	Distributed node registry with tier/filter/status, heartbeat monitor
Infrastructure	Daemons	Process health dashboard with live pings, log tails, restart controls
Infrastructure	Automation	Pipeline hooks and event triggers with webhook test-fire
Infrastructure	Channels	Channel adapters (Discord) with token management and enable/disable
Tools & MCP	Tools	Full tool registry browser with parameter schemas and capability badges
Tools & MCP	MCP Server	Model Context Protocol connections with tool browser and start/stop
Tools & MCP	Codegraph	D3.js force-directed dependency graph, symbol search, impact analysis
Tools & MCP	MCP Gateway	Enterprise MCP server management with rate limiting, health checks
Tools & MCP	Chrome Bridge	Chrome browser automation bridge via MCP
Tools & MCP	Memori	Agent state serialization, checkpointing, and restore
Security	Policies	Enable/disable toggles, inline pattern editing, classification rules
Security	Vault	AES-256-GCM credential store with table view, audit log, export/import
System	Settings	Providers, model router, security supervisor, metrics, observability
System	Quartermaster	Tool orchestration patterns + Model intelligence with strategy config
System	Extensions	Plugin management (installed + discover tabs with marketplace)
System	Analytics	Token usage charts, cost tracking, per-model breakdown
System	Activity	Full audit timeline with level filter, auto-refresh, actor column
Other	Workflows	Visual workflow designer with JSON editor, run history, approvals
Other	Eval Runner	Suite browser, run configuration, results dashboard, regression diff
Other	Eval Memory	Memory-focused evaluation suites for testing recall and search
Other	Prompt Lab	Prompt engineering workspace with version history and testing
Other	PKM	Personal knowledge management — notes, references, and tags
Other	Alcove	Sandboxed workspace for experiments and quick prototyping
Other	Tunnel	Secure tunnel management for exposing local services
System	Teams	Team management with members, roles, and join policies
System	Users	User management with API tokens, permissions, and status controls
Other	Computer Use	Screenshot gallery, action log, display configuration
Other	Remote Agents	Distributed agent deployment with status badges and directive history
Other	Metacognition	Task assessment tester, decision distribution, assessment history
Other	Voice	TTS/STT provider config, VAD threshold, audio format preferences

REST API

GET    /api/health
GET    /api/status
GET    /api/sessions?limit=20
GET    /api/sessions/:id
GET    /api/sessions/:id/messages
GET    /api/sessions/:id/children
GET    /api/sessions/:id/events
POST   /api/sessions/:id/resume
POST   /api/sessions/:id/close
DELETE /api/sessions/:id
GET    /api/jobs?status=pending
POST   /api/jobs
DELETE /api/jobs/:id
GET    /api/memory/search?q=<query>
GET    /api/memory/stats
GET    /api/memory/health
POST   /api/memory/add
GET    /api/memory/reflections
GET    /api/memory/graph/entities
GET    /api/config
PUT    /api/config
GET    /api/providers/configured
GET    /api/providers/:kind/models
GET    /api/plugins
POST   /api/plugins/install
POST   /api/plugins/:name/enable
POST   /api/plugins/:name/disable
DELETE /api/plugins/:name
GET    /api/plugins/check-updates
POST   /api/plugins/update-all
GET    /api/agents
POST   /api/agents
PUT    /api/agents/:id
DELETE /api/agents/:id
GET    /api/services
POST   /api/services
GET    /api/skills
GET    /api/skills/stats
GET    /api/skills/detail?name=<name>
POST   /api/skills
POST   /api/skills/merge
POST   /api/skills/deprecate
POST   /api/skills/promote
POST   /api/skills/load-human
POST   /api/skills/export
GET    /api/skills/dependencies?name=<name>
GET    /api/skills/health?name=<name>
DELETE /api/skills?name=<name>
GET    /api/codegraph/projects
POST   /api/codegraph/index
GET    /api/codegraph/search?q=&project=
POST   /api/codegraph/impact
GET    /api/codegraph/architecture?project=
POST   /api/codegraph/trace
GET    /api/workflows
POST   /api/workflows
GET    /api/workflows/:id
PUT    /api/workflows/:id
DELETE /api/workflows/:id
POST   /api/workflows/:id/run
GET    /api/workflows/runs
GET    /api/workflows/approvals
POST   /api/workflows/approvals/:id
GET    /api/eval/suites
POST   /api/eval/suites
POST   /api/eval/run
GET    /api/eval/runs
GET    /api/eval/runs/:id
GET    /api/eval/baselines
POST   /api/eval/baselines/:runId
DELETE /api/eval/baselines/:id
GET    /api/mcp/connections
POST   /api/mcp/connections
DELETE /api/mcp/connections/:id
POST   /api/mcp/connections/:id/connect
POST   /api/mcp/connections/:id/disconnect
GET    /api/mcp/connections/:id/tools
GET    /api/mcp/server
POST   /api/mcp/server/start
POST   /api/mcp/server/stop
GET    /api/vault/list
POST   /api/vault/store
GET    /api/vault/get/:key
DELETE /api/vault/delete/:key
GET    /api/vault/audit
POST   /api/vault/export
POST   /api/vault/import
GET    /api/computer/screenshots
GET    /api/computer/actions
GET    /api/computer/config
PUT    /api/computer/config
GET    /api/remote/agents
GET    /api/remote/directives
POST   /api/remote/deploy
GET    /api/daemons/health
GET    /api/daemons/:name/logs
POST   /api/daemons/:name/restart
GET    /api/daemons/sockets
POST   /api/import
POST   /api/export
GET    /api/import/history
GET    /api/update/status
POST   /api/update/check
POST   /api/update/install
POST   /api/update/rollback
GET    /api/update/changelog
GET    /api/reflection/schedule
PUT    /api/reflection/schedule
POST   /api/reflection/consolidate
GET    /api/reflection/history
GET    /api/reflection/meta-patterns
GET    /api/providers/comparison
GET    /api/router/history
GET    /api/router/decisions
GET    /api/tools/registry
POST   /api/tools/:name/toggle
GET    /api/tools/:name/stats
GET    /api/memory/privacy
PUT    /api/memory/privacy
GET    /api/memory/heuristics
PUT    /api/memory/heuristics
GET    /api/memory/embeddings
PUT    /api/memory/embeddings
GET    /api/metacognition/history
GET    /api/metacognition/decisions
GET    /api/agents/sub-types
PUT    /api/agents/sub-types/:name
GET    /api/voice/tts
PUT    /api/voice/tts
GET    /api/voice/stt
PUT    /api/voice/stt
PUT    /api/voice/vad
GET    /api/sandbox/config
PUT    /api/sandbox/config
GET    /api/sandbox/images
POST   /api/sandbox/images/pull
DELETE /api/sandbox/images/:id
GET    /api/sandbox/snapshots
POST   /api/sandbox/snapshots
GET    /api/sandbox/snapshots/:id
DELETE /api/sandbox/snapshots/:id
POST   /api/sandbox/snapshots/:id/replicate
GET    /api/sandbox/snapshots/compare
GET    /api/workspace/snapshots
POST   /api/workspace/snapshots
GET    /api/workspace/snapshots/:id
DELETE /api/workspace/snapshots/:id
POST   /api/workspace/snapshots/:id/restore
GET    /api/workspace/snapshots/diff
POST   /api/sandbox/dev-env/generate
GET    /api/sandbox/dev-env/manifest
PUT    /api/sandbox/dev-env/manifest
GET    /api/sandbox/dev-env/list
GET    /api/sandbox/bug-repro
POST   /api/sandbox/bug-repro
GET    /api/sandbox/bug-repro/:id
DELETE /api/sandbox/bug-repro/:id
POST   /api/sandbox/bug-repro/:id/run
GET    /api/security/supervisor
PUT    /api/security/supervisor
GET    /api/security/supervisor/cache
DELETE /api/security/supervisor/cache
GET    /api/security/supervisor/history
GET    /api/security/classification
PUT    /api/security/classification
POST   /api/security/classification/test
GET    /api/soul/templates
GET    /api/workspace/files
GET    /api/workspace/git/status
POST   /api/workspace/git/commit
POST   /api/workspace/git/push
GET    /api/github/repos
GET    /api/github/repos/:owner/:name/pulls
POST   /api/code/exec
POST   /api/upload
POST   /api/voice/transcribe
POST   /api/voice/synthesize
GET    /api/qm/health
GET    /api/qm/recent
GET    /api/mqm/health
GET    /api/lens/recent
GET    /api/dashboard/config
PUT    /api/dashboard/config
GET    /metrics
WS     /ws   (streaming chat)

Security Model

CortexPrism uses a Parallax security model with a three-layer LLM-based access control system:

Agent → Tool Intent → Policy Validator → Executor
                            │
                    [regex allow/deny rules]
                    [capability level (CPL)]
                    [optional human approval]
                            
Agent requests sensitive data →
  Layer 1: Data Classification (SECRET/SENSITIVE/NORMAL/PUBLIC)
  Layer 2: LLM Supervisor (Gemini 2.0 Flash, GPT-4o Mini) with decision caching
  Layer 3: Human Approval (CLI prompts + Web UI modal with 1-hour TTL grants)

Policy rules — regex-based allow/deny rules evaluated against every shell command, file path, and network request. Managed with cortex policy.
LLM security supervisor — sensitive data access (memory, databases, screenshots) requires approval from a fast LLM supervisor with decision caching (1-hour session TTL) and human escalation for uncertain cases.
Data classification — automatic sensitivity detection (SECRET/SENSITIVE/NORMAL/PUBLIC) based on pattern matching (passwords, API keys, PII, confidential markers); all existing data backfilled on first run.
AES-256-GCM vault — all credentials stored encrypted; never written to config in plain text once vaulted.
Activity — append-only audit log in lens.db; every tool call, LLM call, policy decision, and security approval is recorded with timestamp, cost, and session context.
Sandbox isolation — code execution runs in ephemeral Docker/gVisor containers with resource limits (CPU, memory, network disabled by default); subprocess fallback for systems without Docker.

See SECURITY.md for the vulnerability disclosure policy.

Plugin System

CortexPrism supports both Deno module plugins and WASM plugins with sandboxed permissions.

# Install a plugin from the marketplace
cortex plugins install <plugin-name>

# List installed plugins
cortex plugins list

See docs/plugins/ for the full plugin development guide, manifest reference, and submission standards.

Architecture

CortexPrism is a single-process AI agent operating system built on Deno. All state is persisted in SQLite (WAL mode) via @libsql/client. The codebase was modularized in v0.48.6 into 6 coarse packages following a dependency graph core ← gate ← ai ← server ← cli and core ← ai ← infra ← cli.

CLI / Web UI / REST API
        │
   @cortex/ai/agent/loop.ts  ← core agent turn: memory inject → LLM → tool parse → execute
        │
   ┌────┼───────────────────────────────────────────┐
   │    │                                           │
   │    ▼                                           │
   │  @cortex/ai        @cortex/gate               │
   │  agent/ tools/     security/ sandbox/ vfs/     │
   │  memory/ llm/                                  │
   │  pipeline/ skills/                             │
   │                                                │
   │  @cortex/server     @cortex/infra              │
   │  server/ hub/       processes/ services/        │
   │  channels/ a2a/    scheduler/ ipc/             │
   │  mcp/ voice/       triggers/ workflow/          │
   │  workspace/        observability/              │
   │                                                │
   │  @cortex/core      @cortex/cli                  │
   │  config/ db/        cli/ tui/                   │
   │  utils/ i18n/                                   │
   │  plugins/                                       │
   └────────────────────────────────────────────────┘
        │
   SQLite databases (WAL mode)
   cortex.db · memory.db · lens.db · vault.db

Package	Responsibility
`@cortex/core`	Config, database, i18n, logging, paths, plugin system
`@cortex/gate`	Security (policy, vault, supervisor), sandbox, VFS
`@cortex/ai`	Agent loop, tools, memory, LLM providers, pipeline
`@cortex/server`	HTTP server, WebSocket hub, channels, A2A, MCP, voice
`@cortex/infra`	Process supervisor, services, scheduler, IPC, triggers
`@cortex/cli`	CLI commands, TUI

Each package defines contract interfaces in packages/<name>/contracts/ for cross-package boundaries.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a PR.

# Clone and verify
git clone https://github.com/CortexPrism/cortex.git
cd cortex
deno task check    # Type-check — must pass before any PR
deno task lint
deno task fmt
deno task test

Reporting Issues

Bug reports — use the Bug Report template
Feature requests — use the Feature Request template
Security vulnerabilities — see SECURITY.md for the private disclosure process

Roadmap

MCP (Model Context Protocol) server — expose CortexPrism as an MCP server to other clients
Distributed cluster mode — Hub + Node agent distribution across machines
Projects system — workspace-scoped context and memory isolation
Workflow engine — visual no-code agentic workflow builder
Extended LLM provider coverage (24 providers) and streaming improvements
Enhanced desktop app with tray support and native notifications (Tauri — scaffolded)
MCP client mode — connect CortexPrism to external MCP servers
Multi-agent collaboration — peer-to-peer agent communication
Memory embeddings integration with external vector DBs (Chroma, Pinecone, Weaviate)

License

Apache 2.0 — free for personal and commercial use.

Trust

Not scanned yet. Artifacts are graded after they are crawled, so a recently discovered one may have no result for a while.

Versions

git-31235c4d87bd2026-08-04

@cortexprism/cortex

Install

Document

ContextStream Rules

Required Tool Calls

Why These Rules?

Finding Information — Search ContextStream Knowledge, Not Just Code

Freshness Before Assumptions

Past Sessions Are Queryable — USE THEM

Auto-Grounding (in context())

Project Scope Discipline

Code Health and Dependency Recommendations

Response to Notices

System Reminders

Search Protocol

Search Mode Selection:

Output Format Hints:

Two-Phase Search Playbook (recommended):

Plans and Tasks

Memory, Docs & Todos

Skills (IMPORTANT — Do Not Ignore Matched Skills)

Code Search

Context Pressure

IMPORTANT: No Hooks Available

ContextStream Knowledge First

SESSION START PROTOCOL

TRANSCRIPT SAVING (OPTIONAL)

Enable for this chat:

Disable for this chat:

Default policy via MCP config env:

Session ID Guidelines:

FILE INDEXING (CRITICAL)

After Creating/Editing Files:

To Target A Specific Folder Or Recover From Stale Scope:

Signs You Need to Re-index:

SEARCH-FIRST (No PreToolUse Hook)

Before Broad Local Discovery, Check Index Status:

Search Protocol:

Choose Search Mode Intelligently:

Output Format Hints:

Two-Phase Search Pattern (for precision):

When Local Tools Are OK:

CONTEXT COMPACTION (No PreCompact Hook)

When to Save State:

How to Save State:

After Compaction (if context seems lost):

PLANS & TASKS (CRITICAL)

MEMORY & DOCS (CRITICAL)

VERSION UPDATES

Update Commands:

VS Code Copilot Notes

Repository README

CortexPrism

Star History

Table of Contents

Features

AI Providers & Model Routing

Agent Capabilities

Memory System

Skills System

Code Intelligence (Codegraph)

Built-in Tools

Web UI & REST API

Security (Parallax Model + LLM Supervisor)

Computer Use (GUI Automation)

Ops & Extensibility

Requirements

Quick Start

Option 1: One-line installer (recommended)

Option 2: Manual clone

Option 3: Pre-compiled binary

First run

CLI Reference

cortex agent

cortex sandbox run <file>

cortex server start

cortex daemon

cortex git

cortex github

cortex agent sessions

Auto-Grounding (in `context()`)

`cortex agent`

`cortex sandbox run <file>`

`cortex server start`

`cortex daemon`

`cortex git`

`cortex github`

`cortex agent sessions`

`cortex memory`

`cortex vault`

`cortex policy`

`cortex self update`

`cortex mqm`

`cortex agent voice`

`cortex log`

`cortex plugins`

`cortex agent eval`

`cortex eval memory`

`cortex node`

`cortex mcp`

`cortex workflow`

`cortex triggers`

`cortex hooks`

`cortex channels`

`cortex desktop`

`cortex projects`