Cortex

Cortex gives coding agents durable, local memory for one or more Git repositories. A brain is a named set of project knowledge stored on your machine. Cortex exposes the active brain through the Model Context Protocol (MCP). It does not need a hosted service.

How Cortex works

you -> skill or direct MCP call -> project-local MCP server -> active brain

Each repository selects one active brain. Repositories can select the same local brain when they need shared knowledge.

Here, you means the user and agent means Claude Code or Codex. You choose the active brain through /cortex-connect. You decide when to invoke /capture and how to resolve substantive drift. Project hooks give these rules and current Cortex context to the agent without changing a system prompt.

Install

npm install --global @inscapist/cortex
cortex-install

The package includes binaries for macOS and Linux on x64 and ARM64. The installer adds four skills:

• /cortex-connect creates or selects a brain and connects the current repository to Claude Code and Codex.
• /cortex-disconnect disconnects the repository while preserving its brain.
• /ask answers from the brain without changing it.
• /capture requests a durable save only when you invoke it explicitly. It reports whether persistence completed or remains unknown.

Set up a repository

Open the repository in Claude Code or Codex and run:

/cortex-connect

Use a specific name when two repositories must share one brain:

/cortex-connect --name shared-brain

The connector preserves unrelated client configuration while connecting the project's MCP server and lifecycle hooks for both clients. Restart the clients after it succeeds.

To disconnect the repository without deleting its brain, run /cortex-disconnect and restart the clients.

Use it

Ask a question from project memory:

/ask why did we choose SQLite?

Save a decision or constraint from the conversation:

/capture use SQLite so Cortex remains local and requires no service

The setup workflow never writes agent instruction files or configured system prompts, including AGENTS.md and CLAUDE.md.

Tool errors state whether a retry is safe and can include a next action. Follow that result. A transport failure during /capture leaves the write outcome unknown. Cortex has no safe probe for that outcome, so report it and do not retry the capture.

Drift detection

A grounded note links project knowledge to repository source. check_drift checks whether the current source still supports that knowledge and reports three important cases:

• Cosmetic drift: Only formatting or comments changed. The agent can acknowledge the drift. This updates the source baseline without changing the note.
• Substantive drift: Behavior-relevant source changed. Review the note and source. If an intentional code change made a descriptive note stale, revise the note. If code violates a requirement or invariant, fix the code. Acknowledge the new baseline only after the note and code agree.
• Missing or unreadable source: Cortex cannot verify the note. Use apply_mutation_plan to revise the note's source reference, then run check_drift again before you trust it.

check_drift returns the affected notes and suggested next actions. A drift case is resolved when a later check reports the note as current. Cortex does not silently accept substantive drift.

MCP tools

The bundled MCP server exposes 10 tools. Skills use them for normal workflows. The table is a capability map for advanced direct callers. The approval rules described here are explicit invocation for /capture and user resolution of substantive drift. A direct caller that replaces either workflow must preserve its rule.

| Tool | Effect | Purpose | | --- | --- | --- | | apply_mutation_plan | Write | Apply a validated batch of note and edge changes. Cortex applies the full batch or refuses the full batch. | | get_note | Read | Read one or more notes by ID. | | query | Read | List, search, or run the brain's named queries. | | context | Read | Read a bounded set of notes related to a note or source path. | | check_drift | Read | Compare grounded knowledge with current sources and report stale or unverifiable claims. | | schema | Read | Inspect the brain's note types, edge types, and fields. | | analyze_graph | Read | Validate graph structure, find related knowledge or synthesis gaps, and inspect graph health. | | decide_candidate | Write | Accept or discard a pending change produced by a longer agent workflow. /capture does not use candidates. | | get_brain_config | Read | Read the active brain configuration. | | configure_brain | Write | Replace configuration or evolve the brain schema. |

This README is a quick start and a capability map. It is not a direct-call protocol reference. MCP discovery publishes the supported call schema for each tool. Tool results state their outcomes and can include retry guidance or a next action. Follow those results when you call a tool directly.

This README does not teach brain deletion, brain renaming, custom schema design through configure_brain, or low-level storage administration.

License

Cortex is proprietary software. No source license is granted.