cortex-brain

Give your AI agents a company brain.

An MCP server over a plain-markdown knowledge base — cited articles, freshness tracking, open questions, and a safe write path. Your agents stop re-asking the same questions and start consulting (and growing) a shared, auditable memory of how your company actually works.

npx cortex-brain init my-brain      # scaffold a brain (12-domain taxonomy + conventions)
npx cortex-brain my-brain           # serve it to agents over MCP

Why

"AI agents need a living map of how a company works — knowledge extracted from scattered sources into executable form, so agents can actually do the work safely and consistently." — the "Company Brain" thesis (YC RFS)

Generic memory stores remember strings. A brain is structured: who said it, when, how fresh it is, what's still disputed. cortex-brain implements the cortex conventions — proven in production as an internal team wiki pattern — as five MCP tools any agent can use.

The tools

Tool	What it does
brain_search	Keyword search across all articles. Hits carry freshness (current/aging/stale/historical) so agents can judge reliability.
brain_get_article	Full article: markdown + frontmatter — title, domain, tags, sources (who/when/where), linked open questions.
brain_file	The single sanctioned write path: drops knowledge into inbox/ with a metadata header. A curator (human or agent) summarizes it into the wiki later — agents never mutate articles directly.
brain_list_questions	Unresolved conflicts and code/wiki mismatches (q-NNN). Agents that learn an answer file it back.
brain_status	Health report: coverage by domain, freshness distribution, stale articles, empty domains, pending inbox drops.

Use with Claude Code / any MCP client

{
  "mcpServers": {
    "company-brain": {
      "command": "npx",
      "args": ["-y", "cortex-brain", "/path/to/your/brain"]
    }
  }
}

Works on any cortex-style markdown knowledge base — including ones you already have. No database, no embeddings, no API keys: the markdown is the store, git is the history, humans can read every byte.

The conventions

The brain stays trustworthy because of five rules (enforced/encouraged by the tools):

1. Citations — every claim tagged [sN], resolving to a frontmatter sources: entry (who, when, type, ref).
2. Freshness lifecycle — current (≤60d) → aging (≤6mo) → stale; historical is deliberate and never auto-promoted. Computed live from frontmatter dates.
3. State honesty — inbox drops declare state: local | staged | merged | deployed | n/a. Proposed work is never written up as shipped.
4. Single writer — agents write only to inbox/; a curator owns the wiki. Conflicts become open questions, never silent overwrites.
5. Open questions — disagreements are first-class (q-NNN), tracked to resolution.

Article format

---
title: Auth and Permissions
domain: products/atlas
last_updated: 2026-06-01
freshness: current
tags: [auth, rbac]
sources:
  - id: s1
    who: dana
    when: 2026-06-01
    type: meeting
    ref: resource-bin/products/atlas/2026-06-01-auth-sync.md
open_questions: [q-002]
---

# Auth and Permissions

Access tokens expire after 15 minutes. [s1]

CLI

cortex-brain init <dir> [--name <SystemName>]   Scaffold a new brain
cortex-brain <brain-path>                       Serve as MCP (stdio)
cortex-brain <brain-path> --status              Print health report, exit

Programmatic use

import { scanBrain, buildIndex, searchBrain, brainStatus } from "cortex-brain";

const articles = await scanBrain("./my-brain");
const hits = searchBrain(buildIndex(articles), articles, "deployment process");

Limitations (v0.1)

• Keyword search (BM25-style). Hybrid dense retrieval + RRF is on the roadmap.
• The curator (inbox → wiki summarization) is a convention + your agent's job, not yet an automated pipeline. The cortex skeleton includes a curator skill spec for Claude.
• Single brain per server instance.

Development

npm install
npm test                  # vitest, 80%+ coverage enforced
npm run build
node scripts/smoke.mjs    # E2E: real MCP client over stdio, all five tools

License

MIT