# 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.

```bash
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](https://www.ycombinator.com/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](https://github.com/sani-savaliya/cortex-brain#the-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

```json
{
  "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

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

```ts
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](https://github.com/sani-savaliya/cortex-brain)
  includes a curator skill spec for Claude.
- Single brain per server instance.

## Development

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