cortex-brain
sani-savaliya/cortex-brain
Give your AI agents a company brain. MCP server over a markdown knowledge base: cited articles, freshness, open questions, safe writes. (YC RFS: Company Brain)
Instalação
npx convez-ai sani-savaliya/cortex-brain1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
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):
- Citations — every claim tagged
[sN], resolving to a frontmattersources:entry (who, when, type, ref). - Freshness lifecycle —
current(≤60d) →aging(≤6mo) →stale;historicalis deliberate and never auto-promoted. Computed live from frontmatter dates. - State honesty — inbox drops declare
state: local | staged | merged | deployed | n/a. Proposed work is never written up as shipped. - Single writer — agents write only to
inbox/; a curator owns the wiki. Conflicts become open questions, never silent overwrites. - 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