# AiAx Company Brain

> Company Brain is an organization's permission-scoped knowledge graph, readable by any MCP client. Reads are tier filtered, writes are proposals a person approves.

Canonical documentation: https://aiaxagents.ai/en/docs

## Contents

- [Company Brain](https://aiaxagents.ai/en/docs)
- [AiAx CLI](https://aiaxagents.ai/en/docs/cli)
- [Security and governance](https://aiaxagents.ai/en/docs/security)
- [Knowledge sources](https://aiaxagents.ai/en/docs/sources)
- [MCP reference](https://aiaxagents.ai/en/docs/mcp)

## Company Brain

Company Brain is an organization's permission-scoped knowledge graph. It holds what a company knows about itself, and the AI clients your team already uses can read it under the same access rules a person has. Nothing outside AiAx writes to it: new knowledge arrives as a proposal a person approves.

### What it is

Most company knowledge is scattered across documents, tools and people's heads. Company Brain models it as a graph, so an agent can answer how the business actually works and cite the exact pieces of knowledge behind the answer.

- **Nodes**: What the organization is made of: people, departments, projects, processes, systems, agents, strategies, data sources and policies. Every node has an id, a title, a summary and an access level.
- **Relations**: The verbs between nodes: who manages what, which process depends on which system, which policy governs which project. Relations are what turn a list of documents into knowledge.
- **Access**: Every node carries an access level. A reader sees only the nodes their tier allows, and a relation is visible only when both of its ends are.
- **Evidence**: Knowledge a person has confirmed carries a verification date and a review window. Inferred knowledge is marked as a hypothesis and never presented as fact.

| Node types | Relations |
| --- | --- |
| organization, person, department, project, agent | is part of, belongs to, manages, works on, owns, uses, depends on |
| SOP / process, tool, strategy, data source, policy | governs, can access, supports, champions, targets, needs clarification with |

### Everything new is a proposal

An external client can read the graph and propose to it. It cannot write. A proposal lands in the approval inbox in the AiAx portal, where a manager sees the exact stored content and decides. Only an approval changes what the organization knows.

This is the whole trust model in one sentence: a wrong answer from a model becomes a rejected proposal, never a corrupted knowledge base.

- Read tools are annotated as read-only and change nothing.
- Proposal tools need an explicit scope on top of the token, and say so plainly when they lack it.
- The approval binds to the stored proposal, not to what the client says it sent.
- Every tool call is recorded against the token that made it.

### Connect a client in one minute

1. Open Connect AiAx in the portal and create an access token. AiAx shows it once. It is bound to your organization, carries a viewer tier and can be revoked at any time.
2. Put the token in your shell or your client's secure storage. The configuration below only references it, so the token never lands in a file you might share.
3. Add the server to your client with the command for it.
4. Ask the client to read the onboarding status. When it answers, the connection works.

Store the token (placeholder shown)

```
export BRAIN_MCP_TOKEN=brain_xxxxxxxxxxxxxxxxxxxxxxxx
```

> The endpoint is https://aiaxagents.ai/api/mcp. Authentication is a bearer token in the Authorization header.

### Per client

Claude Code

```
claude mcp add-json --scope user aiax '{"type":"http","url":"https://aiaxagents.ai/api/mcp","headers":{"Authorization":"Bearer ${BRAIN_MCP_TOKEN}"}}'
```

Run it in a terminal that already has the token in its environment. The command stores a reference (${BRAIN_MCP_TOKEN}), not the secret.

Cursor: add to .cursor/mcp.json

```
{
  "mcpServers": {
    "aiax": {
      "url": "https://aiaxagents.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${env:BRAIN_MCP_TOKEN}" }
    }
  }
}
```

Keep the token in Cursor's secure storage rather than in the file itself.

- **OpenClaw**: Connects through AiAx CLI. We do not offer manual header configuration, because OpenClaw has no documented secure token reference yet.
- **Claude**: Coming with OAuth. The direct connection is not ready, so we publish no command for it.
- **ChatGPT**: Coming with OAuth. The direct connection is not ready, so we publish no command for it.
- **Obsidian**: The first version of the plugin is built: read-only, with graph, search and sources. Distribution is pending community catalog review.

### A good first prompt

Agents work best when you state the boundary up front. This prompt orients a client and keeps it honest about the approval step.

Paste into your client

```
Connect to AiAx and help me with onboarding. Run get_onboarding_status first. Tell me what is complete, and ask only about the next missing area. Run get_onboarding_action_catalog before you propose a change, and follow its schema. Use query_index and read_concept when Company Brain has relevant knowledge. Do not guess. Show me exactly what you send with propose_onboarding_action. Do not submit anything until I confirm. Every proposal must be approved in AiAx.
```

### Where to go next

- MCP reference: the eight tools, their inputs and the machine contract an agent can parse.
- Security and governance: tokens, tiers, scopes, approvals, freshness and erasure.
- Knowledge sources: which systems can feed the brain and what disconnecting does.
- CLI: the command line tool for signing in and connecting a client.
- The whole documentation set as one plain text page lives at https://aiaxagents.ai/llms-full.txt. Paste it into any model that needs the full picture.

## AiAx CLI

AiAx CLI connects a supported agent client to your organization's Company Brain endpoint. It never prints bearer tokens and it grants no direct write access. Reads stay access controlled, and proposed changes still go to the AiAx approval inbox.

### Installing

The source package is named @aiax/cli and installs the aiax binary.

> We withhold the customer facing install command until the package has a verified registry receipt. Connect AiAx shows the exact command once that release gate passes. We would rather publish nothing than a command that installs the wrong thing.

Setup rejects temporary one shot runners, because a desktop client must not depend on a package cache that can be cleared.

AiAx CLI supports macOS and Linux. On Windows, login fails before the browser authorization starts, so an unsupported machine never mints a server credential it could then lose. We will not call the package Windows ready until it has a platform backed credential store we have tested.

### Commands

Reference

```
aiax auth login
aiax auth status
aiax auth logout
aiax setup claude-code
aiax connect claude-code --dry-run
aiax connect cursor
aiax connect openclaw
aiax doctor [claude-code|cursor|openclaw]
```

aiax setup <client> is the path to use. It opens login only when needed, asks before it updates the client's configuration, and finishes with a remote doctor check. It never passes an automatic yes flag.

The lower level auth, connect and doctor commands are still there for automation and troubleshooting.

- **aiax auth login**: Opens a browser screen where an owner or an administrator has to approve. The exchange uses SHA-256 PKCE and a short lived, state bound one time code, and issues the employee viewer tier by default. The token expires after 90 days.
- **aiax auth status**: Reports whether a credential is present and valid, without printing it.
- **aiax auth logout**: Removes the stored credential from this machine.
- **aiax setup <client>**: The full path for one client: sign in if needed, ask before writing the client configuration, then verify.
- **aiax connect <client>**: Writes the client configuration only. Pass --dry-run to print what it would change and write nothing.
- **aiax doctor [client]**: Verifies the launcher paths and runs an authenticated, read-only initialization and capability check against the endpoint, without printing the token.

### Where credentials live

Credentials are stored in a private directory with owner only files. On macOS and Linux that is the aiax directory under your user configuration directory.

The client configuration never embeds the token. Claude Code, Cursor and OpenClaw start the local bridge from an absolute path. That bridge reads the private credential and connects to the AiAx endpoint over HTTPS using the official MCP SDK. Absolute executable and script paths keep the connection independent of whatever environment a desktop application happens to inherit.

## Security and governance

Connecting an agent cannot widen anyone's access, and it cannot change what the organization knows. Every token carries two independent limits, every write goes through a person, and disconnecting a source deletes its stored credentials immediately.

### Tokens

Access is a bearer token, issued per organization from the portal. AiAx shows the plaintext once at creation and stores only a hash of it, so a copy of our database does not yield a working token. A token can be revoked instantly and can carry an expiry.

- One token belongs to exactly one organization. No token spans two.
- Revocation and expiry are enforced at lookup, not filtered out afterwards.
- A token looks like brain_xxxxxxxxxxxxxxxxxxxxxxxx. Treat it as a password: put it in secure storage, never in a repository.
- The endpoint applies per address rate limiting before it even looks a token up, so probing costs an attacker more than it costs us.

### Viewer tiers decide what is visible

Each token carries a viewer tier. The tier decides which knowledge the token may see, on every read, and matches above it are never returned. A search that reaches knowledge above the tier reports only how many matches were hidden.

| Tier | Sees |
| --- | --- |
| employee | Organization wide baseline knowledge (public, department) |
| manager | The above plus project and management material (project, manager) |
| admin | Everything the organization has recorded |

Nodes are classified with one of these access levels: public, department, project, manager, hr, executive, restricted. A relation is visible only when both of the nodes it joins are visible, so the shape of the graph cannot leak what its contents hide.

### Scopes decide what may be called

A token also carries scopes, independently of its tier. Scopes decide which classes of tools the token may call, and they fail closed: a stored capability that does not parse cleanly is refused outright rather than falling back to a default.

- **brain:read**: Required by every reading tool. Present on every token, because a token that can read nothing is not useful.
- **brain:propose**: Required in addition by every knowledge proposal tool. Granted explicitly, never by default. Without it, a proposal call is refused and registers nothing.
- **outreach:propose**: Required by propose_draft_email, and by nothing else. Granted on top of the proposal scope and never by it, so a token that may propose knowledge cannot propose customer facing email unless it was given this scope as well. It permits proposing an email draft for a manager to approve. It never sends, and it never reads mail.

Reading tools are annotated as read-only in the protocol itself, so a well behaved client knows before it calls that they cannot change anything. They never write to the knowledge graph.

The refusal, verbatim

```
Forbidden: this token is missing the required brain:propose scope. The proposal was NOT registered.
```

### The approval inbox

Nothing external writes to the graph. A proposal from an agent becomes an inbox item in the portal, carrying its kind, its title, its body and the node ids it concerns. A manager reads it and decides.

- The decision binds to the stored proposal. A tampered client cannot smuggle different content past the approval.
- Proposal content is validated on arrival like any other untrusted payload.
- Write volume is rate limited per token and per organization. A refusal states plainly that nothing was registered.
- Approving is what re-derives the graph. Until then, the brain is unchanged.

The rate limit refusal, verbatim

```
Write rate limit reached for this token or organization. The proposal was NOT registered. Try again later.
```

### Freshness lifecycle

Knowledge decays. Every verified source records when a person last confirmed it and how long that confirmation is good for. Once the review window passes, the source is stale, and the system says so rather than quietly serving old answers.

1. A person verifies a source. That records a verification time and starts a review window.
2. When the window elapses, the source reports as stale everywhere it appears, including in the gap list agents read.
3. A review proposal is raised into the approval inbox, asking a person to confirm the knowledge again.
4. Approving it records a fresh verification time and restarts the window.

Rejecting a review snoozes it, it does not silence it. The source keeps reporting as stale for the whole snooze, so the interface never hides the truth. Only the reminder rests, and it comes back when the snooze ends.

### Erasure

Deletion has to reach derived copies, or it is not deletion. Two guarantees matter to a customer.

- **Disconnecting a source**: Stored credentials for that source are deleted immediately. Harvesting stops at once, and reconnecting requires a fresh authorization.
- **Removing a person**: Removing a person from the organization chart, or changing the fields that shape the graph, erases that organization's derived artifacts in the same database transaction: the search embeddings, the cached summaries and the complete history of compiled skill packs. No derived copy of the person survives the change, including their name inside a retained skill pack revision.

Derived stores rebuild from the live graph on the next authorized read, so erasure costs freshness rather than availability. A formal erasure request also runs the documented privacy process across both of our databases: a preview of the exact scope before anything changes, and a verification pass afterwards that proves the identifiers return zero from every erased store.

Credentials for connected sources are held encrypted. Audit records retain identifiers, hashes, states and counts, never message bodies or knowledge content.

## Knowledge sources

A source is a system the brain may read to learn. Harvesting is read-only, everything it finds becomes a proposal, and disconnecting deletes the stored credentials immediately.

### What can be connected

- **Microsoft 365 documents**: Documents and sites your organization already keeps in Microsoft 365. Connected with admin consent in your own Microsoft 365 tenant, and scoped to what you approve.
- **Google Drive**: Documents in Drive, connected through Google's own authorization screen and limited to the access you grant there.
- **Notion**: Pages and databases in Notion, connected through Notion's authorization and limited to the pages you share with the integration.

You connect a source from Connect AiAx in the portal. Authorization happens on the provider's own screen, so AiAx never sees your provider password.

### How harvesting works

1. You authorize the source and choose what it may reach.
2. AiAx reads. It never writes back to the source, and it never deletes anything there.
3. What it finds becomes proposals: candidate nodes, relations and corrections, each carrying where it came from.
4. A person approves in the inbox. Only then does the graph change.

- Read-only by construction. No connector holds a write permission on your system.
- Every proposal carries its provenance, so an approver can see which document a claim came from.
- A source that cannot be read reports as unavailable. It never silently reports as empty, because an empty answer and a broken connection are not the same fact.
- Disconnecting deletes the stored credentials immediately and stops all harvesting.

### What we deliberately do not connect

Transaction systems are not connected. Not the ERP, not the ledger, not the order book.

This is a design decision, not a gap in the roadmap. Company Brain models the knowledge about a process: who owns it, which systems it runs on, which policy governs it, what it is meant to achieve and where it currently breaks. It does not model the transactions the process produces. An invoice line is not knowledge about how invoicing works, and copying millions of them into a knowledge graph buys risk without buying understanding.

In practice, an agent reading Company Brain can tell you how your order to cash process is meant to run and who to ask about it, and will point you at the system of record for the numbers themselves.

## MCP reference

Company Brain is a remote MCP server. This page is the reference an agent needs: the endpoint, the eight tools, and the exact contract for which parts of a response are stable enough to parse.

### Server

| Field | Value |
| --- | --- |
| Name | company-brain |
| Version | 1.0.0 |
| Endpoint | https://aiaxagents.ai/api/mcp |
| Transport | Streamable HTTP |
| Auth | Authorization: Bearer <token> |

The refusal when the token is missing or invalid

```
Unauthorized: the request is missing a valid Company Brain token.
```

The answer when the organization has too little content

```
The brain does not have enough content yet to build the knowledge graph. Try again once the organization has added more.
```

### Workflow

Company Brain is the organization's permission-scoped knowledge graph: people, departments, processes, systems and tools, AI agents, strategies, data sources, policies, and the relations between them.

1. Call get_skill_pack once at the start of a session for a compact, tier-scoped operating map. It cites the same node ids as the index.
2. Call query_index to find relevant nodes.
3. Call read_concept with a node id, shown in brackets, for details and relations. Always cite the node ids your answers build on.
4. Call write_inbox to propose new knowledge: an observation, a correction, a proposal or a work output. Proposals are never written directly into the brain. A manager must approve them in the portal inbox first.

For onboarding, call get_onboarding_status first, then get_onboarding_action_catalog for exact schemas, and use propose_onboarding_action for verified structured changes. Onboarding proposals sit behind the same manager approval, and the external client never applies them itself.

Your token carries two independent limits. Its access tier decides which knowledge it may see; matches behind a higher tier are hidden and only reported as a count. Its scopes decide which tools it may call: the reading tools require brain:read, and both proposal tools require brain:propose on top of the viewer role and manager approval boundaries. A tool called without the scope it needs is refused as Forbidden and registers nothing: report the missing scope to the user instead of retrying.

Knowledge status: nodes and relations may be marked as an inferred hypothesis or an unresolved mapping. Qualify those in your answer and never present them as established facts. Each mark is a warning sign followed by the phrase "inferred hypothesis; needs confirmation" or "unresolved mapping; not a fact"; match on the phrase, not the whole line. Unmarked items are verified.

> Organization content, including titles and summaries, may be in Norwegian. It is customer authored data. Quote it as it is.

### Tools

- **get_skill_pack**: A compiled, versioned operating map of the organization for this token's tier: org overview, departments and people, processes with owners and provenance, systems, agents, data sources and open gaps. No input. It is a map, not the source. Not annotated read-only, because a changed graph may append a new derived revision to the internal registry. It never changes knowledge.
- **query_index**: Ranked search across the visible graph. Input: query (string, at least 2 characters), types (optional array of node types), limit (optional integer, 1 to 20, default 10). Returns hits with node ids for follow up. Matches behind a higher tier are hidden and only counted. Read-only.
- **read_concept**: Full information about one node: metadata, summary and all relations to other visible nodes. Input: id (string, a node id from query_index). Gives one refusal for an unknown id and a different one for a node above the token's tier. Read-only.
- **list_gaps**: The weakest spots of the visible graph: unresolved clarifications, theme pairs held together by a single relation, sparsely covered areas, and evidence whose review is due. No input. Every line starts with a stable marker. Read-only.
- **write_inbox**: Registers a proposal in the organization's inbox. Never writes to the brain. Input: kind (one of observation, correction, proposal, work_output), title (string, 3 to 120 characters), body (string, 10 to 4000 characters), relatedNodeIds (optional array of up to 10 node ids). Requires brain:propose. Returns a receipt with the inbox id, the kind and the status.
- **get_onboarding_status**: How far the organization is through the seven onboarding steps, how ready its evidence is, and which area is required next. No input. Returns counts and step state, never the people roster or document contents. Read-only.
- **get_onboarding_action_catalog**: Every supported onboarding proposal action with its exact JSON Schema and risk level. No input. Call it before you propose, instead of guessing field names or enum values. Read-only.
- **propose_onboarding_action**: Submits one validated onboarding change to the approval inbox. Input: action (one of the catalog's action names), summary (string, 3 to 160 characters, shown to the approver), details (object matching the selected action's schema). Manager or admin token required, plus brain:propose. Never applies the change itself.
- **propose_draft_email**: Creates a proposal for an email draft. Input: to (array of 1 to 10 email addresses), subject (string, 1 to 300 characters), bodyText (string, 1 to 20000 characters). Requires outreach:propose. It does not create the draft and it does not send anything: a manager must approve the proposal first, and on approval the draft is created in the approver's own mailbox for them to review, edit and send by hand. Nothing is ever sent by AiAx. The approval id is derived from the content, so a replayed call resolves to the proposal that already exists.

### The machine contract

Every answer mixes two registers, and only one of them is a contract. Display text is rendered in the organization's own language, so a client that keys on anything display shaped breaks the day an organization switches language.

Stable, locale independent, safe to parse:

- Node ids in [brackets], and the wiki reference module and entity ids.
- Node type labels, always the English set: organization, person, department, project, agent, SOP / process, tool, strategy, data source, policy.
- Relation verbs, always the English set: is part of, belongs to, manages, works on, owns, uses, depends on, governs, can access, supports, champions, targets, needs clarification with.
- Access, rendered as the enum literal itself and never its label: public, department, project, manager, hr, executive, restricted.
- The two knowledge status mark phrases, "inferred hypothesis; needs confirmation" and "unresolved mapping; not a fact", each preceded by a warning sign in the emitted line; match on the phrase.
- Metadata keys, always English: Title, Coverage, Owner, Relation, Model, Approval threshold, Score, Quadrant, Estimated savings/year.
- Freshness fields (Evidence status, Verified, Review by) and every other timestamp, as ISO 8601 instants and never formatted dates.
- Gap markers, one per line, of the form [gap:<kind>] where kind is one of clarification, thin_link, sparse_theme, stale_evidence.
- Input bounds: the schemas listed under Tools, including the limit range and the enums.
- Refusal and empty state answers, verbatim, and the two distinct read_concept denials.
- Write receipts and skill pack registry lines, including the revision, the content hash and the generation timestamp.

Not a contract, and display text in the organization's language: titles, summaries, metadata values, tags, gap sentences and every section heading. Quote them, never parse them.

A gap line, marker first

```
- [gap:stale_evidence] <sentence in the organization's language>
```