Resume engineering work with evidence.

Cortex is a local-first, MCP-native engineering state plane for coding agents. It links tasks, attempts, evidence, decisions, artifacts, verification, and handoffs so a human or another agent can continue from the latest trustworthy state.

task → attempt → evidence → decision → artifact → verification → handoff

Agent A stops. Cortex records what happened and why. Agent B resumes with the repository state, evidence, blockers, and next safe action already in view.

Why Cortex

Coding work is scattered across chat sessions, branches, issue comments, Markdown files, Git history, CI logs, and human memory. Cortex connects those signals without replacing Git, CI, issue trackers, or the agent runtime.

• Evidence before memory: claims keep their source, authority, scope, and freshness.
• Repository-aware: task state is scoped to the repository, branch, commit, and worktree.
• Local-first: start with an inspectable local record; add synchronization only when it creates team value.
• Portable: consume the same state from the CLI, MCP, VS Code, Codex, OpenCode, and other compatible agents.
• Honest by design: an agent summary is not treated as verified until Git, tests, CI, tools, files, or a human support it.

What works today

Surface	Available now
CLI	setup, install, project scan, search, task start/resume, evidence capture, handoff, drift detection, and verification
MCP server	Project-scoped context plus the continuity tools cortex_start, cortex_capture, cortex_handoff, cortex_resume, cortex_detect, and cortex_verify
VS Code	Project scanning, context records, tool discovery, model-assisted analysis, and MCP setup
Storage	Local SQLite with FTS5 search and project isolation
Agent bridge	Codex and OpenCode lifecycle adapters that capture high-signal events with deduplication and redaction

See the capability matrix for transport and editor-specific support. The lifecycle is implemented in the CLI/MCP foundation; integrations are intentionally tracked separately from the core record.

Quick start

Use the published CLI

Install Bun 1.x, then run this from the repository you want to connect:

bunx @ecuabyte/cortex-cli setup

This configures detected editors, writes project-scoped agent instructions, and scans the current project. For a reusable installation, install the CLI globally:

bun add --global @ecuabyte/cortex-cli
cortex setup

Create and hand off a task

cortex start "Implement database migrations" --acceptance "Migration tests pass" --agent codex
# Capture the taskId and attemptId from the JSON response.
cortex capture --task <taskId> --attempt <attemptId> \
  --kind decision --summary "Keep migrations reversible" --source human
cortex handoff --task <taskId> --attempt <attemptId> \
  --next "Run the migration test suite"

# In the next session or agent:
cortex resume <taskId>
cortex detect <taskId>
cortex verify --task <taskId> --attempt <attemptId> \
  --summary "Migration tests pass" --source test

Connect an MCP client manually

{
  "mcpServers": {
    "cortex": {
      "command": "bunx",
      "args": ["@ecuabyte/cortex-mcp-server"]
    }
  }
}

Use the universal setup guide for Cursor, Windsurf, Claude, Gemini, Zed, and compatible MCP clients.

Development

git clone https://github.com/EcuaByte-lat/Cortex.git
cd Cortex
bun install
bun run build
bun run typecheck
bun run test:all

Useful documentation:

• Quick start
• CLI and editor installation
• MCP and universal setup
• Architecture and handoff contract
• Roadmap
• Contributing
• Support
• Security policy

Product direction

Cortex is not a generic personal-memory assistant, a replacement for Git/CI/issues, an agent runtime, or an MCP registry. Its wedge is verified continuation: fewer repeated investigations, fewer stale assumptions, and a clear next step when work changes hands.

The north-star metric is verified continuations per active project per week. Read the product direction, market research, distribution strategy, and adoption model for the full thesis.

Privacy boundary

Cortex is local-first, not a promise that every operation is offline. Embeddings or other providers may receive data when explicitly configured. Review the active provider and keep egress visible, configurable, and testable.

License

MIT. See LICENSE.