Skip to content

Plugins

Cortex provides deep agent integration through native plugins for Claude Code and OpenCode.

Claude Code Plugin

The Claude Code plugin adds lifecycle hooks that automate memory management.

Bare MCP vs Plugin

Feature Bare MCP Plugin
Memory tools yes yes
Auto session tracking - yes
Compaction recovery - yes
Save nudge (15 min) - yes
Passive capture - yes
Memory Protocol injection - yes
ToolSearch auto-loading - yes

Plugin Structure

plugin/claude-code/
  .claude-plugin/plugin.json    Plugin descriptor
  hooks/hooks.json              5 lifecycle hooks
  scripts/
    _helpers.sh                 Shared helpers (project detection)
    session-start.sh            Load memory context on startup
    post-compaction.sh          Recover context after compaction
    user-prompt-submit.sh       First-message tool loading + save nudge
    subagent-stop.sh            Passive capture from subagent output
    session-stop.sh             Mark session as ended
  skills/memory/SKILL.md        Memory Protocol for the agent

Lifecycle Hooks

SessionStart (startup | clear)

  1. Ensures cortex HTTP server is running
  2. Creates session via HTTP API
  3. Fetches memory context for the project
  4. Injects Memory Protocol + context into Claude, detailing CORE tools (cortex_save, cortex_search, cortex_context, cortex_session_summary, cortex_get_observation, cortex_update) and deferred tools via ToolSearch.

SessionStart (compact)

  1. Ensures session exists
  2. Injects Memory Protocol + compaction recovery instructions
  3. Instructs agent to: save compacted summary → load context → then continue

UserPromptSubmit

  • First message: Injects ToolSearch selection to load the core tools and initial context tools (cortex_save, cortex_search, cortex_context, cortex_session_summary, cortex_get_observation, cortex_update, cortex_relate, cortex_graph, cortex_get_agent_context, cortex_revision_history).
  • Subsequent: If > 15 min since last save and session > 5 min old, nudges agent to save

SubagentStop (async)

  • Captures subagent output and saves as passive observation

Stop (async)

  • Marks session as ended via HTTP API

All hooks use CORTEX_HTTP_PORT (default 7438). CORTEX_PORT is not supported.

Memory Protocol & Profiles

The skills/memory/SKILL.md file defines mandatory behaviors for the agent across supported profiles:

  • Profiles Supported: agent (22 tools, default), dev (11 tools), and minimal (5 tools). Administrative and temporal operations are handled via CLI/REST, keeping the agent context zero-bloat.
  • Proactive saves: After decisions, bugfixes, discoveries, patterns, preferences.
  • Search triggers: When user recalls, when starting related work, on first message (auto, direct, semantic, multi_hop).
  • Knowledge graph: Use cortex_relate and cortex_graph_path to map and traverse relationships.
  • Codebase AST & Impact: Query symbols via cortex_get_code_symbols, map impacted tests with cortex_code_tests, and evaluate blast radius with cortex_get_blast_radius.
  • Session close: Mandatory cortex_session_summary with Goal/Discoveries/Accomplished/Next Steps/Relevant Files.
  • Compaction recovery: 4-step mandatory protocol.

OpenCode Plugin

The TypeScript plugin (plugin/opencode/cortex.ts) connects OpenCode's event system to Cortex.

Features

  • Auto-start: Detects if cortex server is running, starts it if not
  • Session tracking: Creates sessions on session.created events
  • Session lifecycle: Ends primary sessions on session.deleted
  • Sub-agent suppression: Detects Task() sub-agents and skips session registration
  • User prompt capture: Saves prompts to user_prompts via chat.message
  • Tool tracking: Counts non-Cortex tool calls per session using an exhaustive CORTEX_TOOLS allowlist
  • Passive capture: Extracts learnings from Task tool output
  • Mode-Aware Memory Instructions: Dynamically injects instructions based on the active mode:
  • Server Mode (PostgreSQL): UUID transport IDs, corporate governance (cortex_get_project_context), domain skills (cortex_list_skills, cortex_get_skill), and unified resolution (cortex_resolve_query).
  • Local / Hybrid Mode (SQLite Zero-CGO): Numeric integer IDs, AST intelligence (cortex_get_code_symbols, cortex_code_map, cortex_code_tests), and knowledge graph paths (cortex_graph_path).
  • Compaction recovery: Injects context + instructions via experimental.session.compacting

Setup and Modular Profiles

cortex setup opencode [--profile=agent|dev|minimal] installs both the MCP registration (~/.config/opencode/cortex-mcp.json) and the managed plugin (~/.config/opencode/plugins/cortex.ts).

The TypeScript source is embedded in every Cortex binary, including release archives and go install builds. Running setup again replaces the managed plugin with the version embedded in the current binary.

Binary Path Resolution

The plugin uses a 3-tier fallback for the cortex binary: 1. CORTEX_BIN environment variable (explicit override) 2. Bun.which("cortex") (runtime PATH lookup) 3. Absolute baked-in path (headless/systemd fallback)

Local Model Compatibility

The system prompt is appended to the last existing system message (not pushed as a new one) to avoid breaking models that only allow a single system block (Qwen, Mistral via llama.cpp).

Privacy

Content wrapped in <private>...</private> tags is stripped by the OpenCode plugin before its HTTP call. This is plugin-specific behavior; other MCP/HTTP clients do not automatically redact those tags.

<private>API_KEY=sk-1234</private>  →  [REDACTED]

Testing

Both plugins ship reproducible gates that CI enforces on every pull request and again before release.

  • OpenCode (plugin/opencode): an isolated npm subpackage (@cortex/plugin-opencode, Node >= 24) with its own committed lockfile. Run npm ci && npm test inside the directory; the Vitest harness (vitest run) exercises the cortex.ts contract tests without a live Cortex server or network access.
  • Claude Code (plugin/claude-code): scripts/hooks_test.sh is a deterministic, network-free contract harness that stubs curl and the cortex binary with fixtures. It requires bash, jq, python3, and coreutils timeout; if any of them is missing it exits with 127 so the gate is reported BLOCKED instead of silently passing.

Local vs CI: on Windows workstations without jq (or without a full bash toolchain) the Claude harness is BLOCKED locally — that is expected, not a failure of the plugin. The ubuntu-latest runners in .github/workflows/ci.yml install the dependencies explicitly and are the authoritative executor. The OpenCode tests run anywhere Node >= 24 is available, including Windows.