Cortex

One global, local-only Markdown brain that documents all your projects — for Claude Code and Codex.

🧠 One brain · 🗂️ Markdown only · 🤖 Claude Code + Codex · 📦 npx-first · 🔒 secret-scanned · 🧾 git-audited

---

What it is

Cortex is a global knowledge brain that lives on your machine as a folder of plain Markdown (~/brain by default). Every project you work on is documented inside that one brain — not scattered across per-repo docs/brain/ folders. Open it in any editor; it is just files.

• Local-only. No server, no cloud, no telemetry. Your brain never leaves your disk.
• Built for coding agents. Claude Code and Codex read it at session start and query it on demand.
• npx-first. Try it without installing anything.
• git-audited. Every write commits locally so you have a full, reversible history. No remote is ever added; nothing is ever pushed.
• Secret-scanned. Every write passes a secret gate that refuses high-confidence leaks and redacts low-confidence ones.

This is currently positioned for personal reuse — a tool Aviv built for his own multi-project workflow and is sharing. It is not yet a team product (see Limitations).

Quick start

# Try it with npx — no install
npx @avivk5498/cortex init        # create ~/brain
brain bootstrap                   # document the project in the current directory
brain build                       # (re)build the search index
brain check                       # validate the brain

Or install globally:

npm i -g @avivk5498/cortex
brain init

Wire up your agent once:

brain agent-hook-setup claude     # Claude Code
brain agent-hook-setup codex      # Codex

The global brain

A Cortex brain is a single directory. Projects are pages inside it, organized by type:

~/brain/
├── SCHEMA.md                 # the page taxonomy + frontmatter contract
├── MOC.md                    # Map of Content — the hub index, hand-curated
├── log.md                    # append-only operation log
├── AGENTS.md                 # generic agent contract
├── _sync-state.json          # bookkeeping (counts, known projects, install flags)
├── inbox/
│   └── scratchpad.md         # capture buffer; non-template lines = "pending"
├── sources/                  # raw source material (binaries gitignored)
├── adapters/                 # adapter-owned, brain-committed snippets
└── pages/
    ├── projects/<slug>.md            # project overview (one per project)
    ├── project/<slug>/overview.md    # nested per-project detail
    ├── reference/<slug>-important-files.md
    ├── decision/<slug>-*.md          # decisions, with citations
    └── gotcha/<slug>-*.md            # sharp edges / footguns

Project pages carry citation metadata — project_path, project_slug, and a cites: list of {ref: path:line, sha: <git hash-object>} — so brain check can detect when the underlying code has drifted from what the brain claims. The full contract is documented in SCHEMA.md inside every brain.

How a project gets into the brain

brain bootstrap (run from inside a repo) does not invent knowledge. It collects facts about the repo and writes an agent prompt to inbox/bootstrap-<slug>.md. Your coding agent then synthesizes the project pages — with citations — and writes them through Cortex's safe-write path. The tool prepares; the agent fills in the knowledge. See the agentic bootstrap flow.

Command reference

Command	What it does	Key flags
brain init	Scaffold a new global brain (dirs, SCHEMA/MOC/log/AGENTS, git repo, index).	--force, --agent <x>, --json
brain bootstrap	Collect repo facts and prepare an agent prompt to document the current project.	--dry-run, --json
brain build	Rebuild the search index and commit it.	--json
brain query "<text>"	Rank brain pages for a query.	--limit N, --important, --bundle, --json
brain check	Validate the brain: required files, stale index, frontmatter, MOC orphans, stale citations, pending inbox, dirty git.	--verbose, --json
brain status	Snapshot: git state, last op, index freshness, counts, adapter install status.	--json
brain sync	Deterministic pass (reindex + check + state) then emit the agent task block for durable-learning capture.	--json
brain update-brain	Emit an agent prompt to sweep the current conversation for durable knowledge and file confirmed items.	--dry-run, --json
brain session-context	Emit the matched project page + MOC + routing instruction (used by the SessionStart hook).	--hook-json, --agent <x>
brain agent-hook-setup <agent>	Install the Claude / Codex / generic adapter.	--force, --json

Exit codes: 0 success/clean · 1 validation findings or empty query · 2 runtime/config error.

BRAIN_HOME / --brain

The brain home is ~/brain by default. Override it with the BRAIN_HOME environment variable, or per-invocation with --brain PATH:

BRAIN_HOME=~/work-brain brain status
brain --brain /tmp/scratch-brain init

--brain wins over BRAIN_HOME, which wins over the default.

Claude setup

brain agent-hook-setup claude

This writes into ~/.claude (the Claude adapter; see docs/claude-adapter.md):

• ~/.claude/commands/brain-bootstrap.md, brain-sync.md, brain-update.md, brain-query.md — slash commands that drive the brain CLI flows.
• ~/.claude/settings.json — a SessionStart hook is merged in that runs brain session-context --hook-json --agent claude. Your existing settings are preserved; the file is backed up to settings.json.bak before writing.

Re-running without --force skips files that already exist (reported as skipped).

Codex setup

brain agent-hook-setup codex

This writes into ~/.codex (the Codex adapter; see docs/codex-adapter.md):

• ~/.codex/AGENTS.md — a marked block (<!-- BEGIN cortex-brain --> … <!-- END cortex-brain -->) with a compact pointer to the brain and how to query it. Re-runs replace only that block; the rest of your AGENTS.md is untouched. The block is kept small because all AGENTS.md files share a 32 KiB cap.
• ~/.codex/prompts/brain-query.md, brain-sync.md, brain-update.md, brain-bootstrap.md, brain-status.md — prompt commands ($ARGUMENTS-based).
• ~/.codex/hooks.json — a SessionStart (and PreCompact) command hook running brain session-context --hook-json --agent codex, merged with any existing hooks.

Trust prompt: Codex asks you to trust the hook on first run. If your environment sets allow_managed_hooks_only, user-level hooks are blocked and the SessionStart injection will not fire — fall back to the AGENTS.md pointer. Codex prompt commands are local-only and require a restart to reload.

The agentic bootstrap flow

Cortex deliberately separates fact collection (deterministic, done by the tool) from knowledge synthesis (judgment, done by the agent):

1. You run brain bootstrap inside a repo. Cortex collects context (repo metadata, file tree, key facts).
2. Cortex writes an agent prompt to inbox/bootstrap-<slug>.md and commits it. The prompt names the exact pages to write (pages/projects/<slug>.md, pages/reference/<slug>-important-files.md, optional decisions/gotchas/sources) and requires citations (ref: path:line, sha: via git hash-object).
3. Your agent reads the prompt, studies the repo, and writes the pages through Cortex's safe-write path — so every page is secret-scanned and committed.
4. brain build indexes the new pages; brain check validates them.

The tool never makes up knowledge about your code; the agent does the writing, Cortex enforces the discipline.

Local git & audit model

Every command that writes to the brain commits it locally with a brain: <message> message. This gives you a complete, reversible audit trail (git log inside ~/brain).

• No remote is ever added.
• Nothing is ever pushed.
• Adapter files live outside the brain (in ~/.claude, ~/.codex) and are not committed to the brain — only the brain's record of the install is.

Secret scanning

Every write passes through a secret gate before it touches disk:

• Refuses high-confidence secrets — the write is aborted (SecretRefusal) and nothing is written.
• Redacts low-confidence matches in place and writes the redacted content.
• Blocks by filename — writes to .env, *.pem, id_*, credentials*, and gitignored paths are refused outright.

brain check also flags any staged file that matches the secret filename rules, so a leak can't slip through the commit.

Safety guarantees

• Local-only; no network calls, no telemetry.
• No git remote, no push, ever.
• High-confidence secrets are refused, not just redacted.
• Adapter installs back up settings.json and never overwrite adapter-owned files without --force.
• Writes that would fail the commit leave your files intact and return a runtime error.

Limitations

• Single-user. One brain, one author. No team workflow yet.
• No merge model. There is no conflict resolution for concurrent editors.
• No embeddings. Search is token-overlap ranking, not vector/semantic search.

Troubleshooting

• already initialized (use --force) — a brain already exists at the target home. Use --force to re-scaffold, or point elsewhere with --brain / BRAIN_HOME.
• check reports a stale index — run brain build.
• check reports stale citations — the cited code changed; have your agent re-verify and update the page's sha.
• Codex SessionStart hook never fires — your environment likely enforces allow_managed_hooks_only; rely on the AGENTS.md pointer instead.
• Claude slash commands missing — re-run brain agent-hook-setup claude; pass --force to refresh existing command files.
• brain status shows the adapter as not installed — run the matching brain agent-hook-setup <agent>.

Testing

npm test                  # full suite
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:regression

License

MIT © 2026 Aviv Kaplan. See LICENSE.