# 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

```text
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

```sh
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:

```text
/cortex-connect
```

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

```text
/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:

```text
/ask why did we choose SQLite?
```

Save a decision or constraint from the conversation:

```text
/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.