cbrain Docs

cbrain · company brain

An enterprise knowledge brain for AI agents: keep all company knowledge in one markdown directory (in git), then layer semantic search and read/write so every agent can search first and capture knowledge as they work.

Core thesis: markdown-in-git is the only source of truth. Databases, indexes, and vectors are rebuildable derived caches. Knowledge always belongs to you — take it with you anytime.

People manage orgs, knowledge bases, and permissions in the console (/dash); agents search and capture knowledge with cbrain. On-disk format follows vendor-neutral OKF and an Obsidian Flavored Markdown subset — Obsidian, MkDocs, and other tools can read it directly.

Capabilities

Semantic search

Vector nearest-neighbor plus token-budget trimming, Chinese-first. Every hit carries a source citation — search before answering, never invent.

Knowledge capture

Meeting notes, customer updates, and conclusions go into the brain in one shot. Raw material lands in raw; maintainable knowledge in wiki.

Smart edits

Describe intent in natural language (e.g. "change contact A to B"). The brain reads real content and rewrites precisely — multi-page changes in one atomic commit.

Permission isolation

Tenant / clearance / department isolation. Unauthorized content is not returned and never hinted at — fail-closed by design.

Git as truth

Every write is a git commit — auditable and reversible. Rebuild the entire index with one command if it breaks.

Self-maintaining

Scheduled incremental reindexing plus weekly alignment digests keep the knowledge base fresh on its own.

Core concepts

Concept	Meaning
Organization (Org)	A collaboration group: members, invites, and roles. An org can host multiple knowledge bases.
Knowledge base (project)	A fully isolated tenant: its own git repo and search index. Zero visibility across knowledge bases.
Page	A markdown file identified by slug (path without .md), e.g. `wiki/customers/<company.name>/overview`.
raw / wiki layers	`raw/` holds immutable evidence (original notes, imports — append-only); `wiki/` holds conclusions and profiles agents can maintain, citing raw via frontmatter.
AGENTS page	The knowledge base meta-rules layer: directory map, naming and archival rules. Injected into agent context automatically; admins-only; not searched.
Department (compartment)	Horizontal visibility: bind top-level directories to departments. Sales cannot see supply chain; public dirs are visible to everyone.
Clearance (visibility)	Vertical sensitivity: `team` (default) / `company` / `admin`. Lower-clearance readers have no awareness of higher-clearance content.

Quick start (admins)

Connect a team to the brain in five minutes:

Open https://cbrain.intelli-spectrum.com/dash, create an account, and sign in.

Create an org and knowledge base

Home → "New organization" → enter the org → "Create knowledge base". The system creates the tenant, initializes git, and makes you the owner.

Invite members and set roles

Invite collaborators on the org page: viewer (read-only) / contributor (read-write · team clearance) / editor (read-write · company clearance) / admin (manage). Role changes apply immediately — no re-auth needed.

Scope directory visibility by department (optional)

On the knowledge base Content page, bind top-level directories to departments (company-wide / specific department / admins only), then assign departments under Members. All documents are private by default: unbound directories are visible to owners/admins only.

Have members connect their agents

On the knowledge base Agent setup page, members copy one prompt into their agent (Claude / Codex / Cursor, etc.). The agent installs and authorizes itself — see below.

Agent setup (members)

Easiest path: paste the prompt below into your agent chat and let it finish the rest.

Please read https://cbrain.intelli-spectrum.com/doc/cli-setup.md and follow the steps to install and configure the cbrain CLI for me.

The agent runs a four-step setup (you can also do it manually):

Install the CLI

npm install -g cbrain

Install the skill (teaches the agent usage discipline)

npx skills add https://cbrain.intelli-spectrum.com --skill cbrain -g -y

Authorize in the browser

The command opens a browser. Sign in and pick the knowledge base to authorize. The CLI reads and writes with your role; role changes apply immediately.

cbrain auth login

Verify identity

cbrain me

After authorization, ask your agent things like: "What is the status of project A?", "Save these meeting notes to the brain", or "Summarize recent customer activity."

Common commands

Agents (or you) operate the brain with cbrain:

Action	Command	Purpose
Semantic search	`cbrain search "<question>" [--deep]`	Search before answering; `--deep` widens recall; `--include-raw` includes raw evidence
Write knowledge	`cbrain write <slug> --type <Type> [--from raw/a]`	Advanced direct write, only when the caller intentionally provides the final wiki body
Ingest evidence	`cbrain ingest --body-file <path> [--digest "<intent>"]`	Before writing, the server reads AGENTS and plans a semantic raw path, YAML tags, and wiki routes; ambiguity returns a question with zero writes
Update knowledge	`cbrain update "<intent>" [--dry-run]`	Describe intent; the brain rewrites precisely; multi-page atomic commit
Q&A	`cbrain ask "<intent>"`	Read-only search / synthesis with [[source]] citations
Read a page	`cbrain read <slug>`	Read a page by slug
Browse	`cbrain tree / cbrain list --prefix ...`	Browse structure and visible pages
Identity	`cbrain me`	Current authorized knowledge base, capabilities, and scale

Typical workflows

Ask: answer company questions

Agent discipline is search before answering: any company fact is retrieved with search first; answers only from hits, each claim cited as [[source slug]]. If nothing is found, say so — never invent.

Store: capture meeting notes

# Save the body to a UTF-8 file; the caller does not choose raw/wiki directories.
# Never pipe non-ASCII text through a Windows shell (it becomes "?")
cbrain ingest --type RawDocument --body-file notes.md

# If needs_confirmation is returned, nothing was written; ask and retry with the same body
cbrain ingest --body-file notes.md --confirm-route <candidate route>

Edit: knowledge changed

# Describe intent; multi-page changes in one commit — all or nothing
cbrain update "Change the ACME contact from A to B and add today's handoff note"

# Preview changes without writing
cbrain update "ACME contact A→B" --dry-run

Permission model

cbrain describes "who can do what to what" on three orthogonal axes, all fail-closed (deny by default):

Axis	Values	Controls
Capability scope	`read` / `write` / `admin`	Which operations can run
Clearance	`team` / `company` / `admin`	Vertical: how sensitive content can be read
Departments (compartments)	Department set (e.g. `sales`)	Horizontal: which directory partitions can be read/written

Console roles are presets of these three axes. Reading a page requires both clearance and department visibility. Key properties:

No existence hints: unauthorized pages look identical to missing in search, list, and read — byte-for-byte. Responses cannot probe hidden content.
Zero cross-tenant leak: knowledge bases are isolated at the application layer and with PostgreSQL row-level security (RLS).
Audit: non-full-access reads are logged end-to-end; denied attempts are recorded separately.

More resources

Resource	URL	Notes
Console	`/dash`	Orgs / knowledge bases / members / Agent setup, content browsing
Agent setup guide	`/doc/cli-setup.md`	One-page install guide written for agents
Skill discovery	`/.well-known/skills/`	Agent Skills Discovery endpoint (for npx skills add)
Data-plane API	`/v1/ops/*` · `/mcp`	HTTP ops API and MCP connector (Bearer token auth)

cbrain — markdown-in-git is the source of truth; everything else can be rebuilt.