INITE Brain

INITE Brain

Open-source memory for AI agents: a bitemporal knowledge graph with provenance, over MCP and REST.

Website · Quick start · Architecture · Domain Packs · Getting started · Docs · Agent guide

Quick start

Needs Docker with Compose v2, openssl, and an OpenAI API key (the default model configuration). Runs the released image (linux/amd64 and linux/arm64) with SurrealDB; no clone, no build.

: "${OPENAI_API_KEY:?export OPENAI_API_KEY first}"
mkdir inite-brain && cd inite-brain
curl -fsSLO https://raw.githubusercontent.com/inite-ai/inite-brain-service/main/docker-compose.quickstart.yml
BRAIN_KEY="brain_$(openssl rand -hex 24)"
KEY_HASH="$(printf %s "$BRAIN_KEY" | openssl dgst -sha256 -r | cut -d' ' -f1)"
cat > .env <<EOF
BRAIN_VERSION=2.4
OPENAI_API_KEY=$OPENAI_API_KEY
BRAIN_API_KEYS='[{"keyHash":"sha256:$KEY_HASH","companyId":"co_demo","scopes":["brain:read","brain:write"]}]'
SURREALDB_PASSWORD=$(openssl rand -hex 24)
SURREALDB_SCOPED_PASS=$(openssl rand -hex 24)
FORGET_HMAC_KEY=$(openssl rand -hex 32)
EOF
docker compose -f docker-compose.quickstart.yml up -d --wait
export BRAIN_URL=http://localhost:3030 BRAIN_KEY
curl "$BRAIN_URL/health"
echo "API key (shown once, only its hash is stored): $BRAIN_KEY"

Then remember something and ask about it, or point an MCP client at http://localhost:3030/mcp with Authorization: Bearer $BRAIN_KEY. BRAIN_VERSION takes X.Y (newest patch of that release) or vX.Y.Z; :latest is overwritten by the main-branch deploy. The first start downloads the local ONNX models into a volume, so the first write can take a few minutes; later ones do not. Hosted service, running from source, and production: Getting started.

Why not Mem0, Zep or Letta?

• Mem0 is quicker to adopt: an add/search API, a managed platform and many framework integrations. Brain asks for more up front (a tenant, scoped keys, userId on personal memory) and in exchange keeps both valid time and knowledge time on every fact. A conflicting write supersedes the earlier fact or is parked as COMPETING; it does not silently overwrite.
• Zep (Graphiti) is the closest design: Graphiti is also a temporal knowledge graph, and you can embed it as a Python library over a graph database. Choose it if you want memory inside your own process. Brain is a service: a separate database per tenant, API keys scoped to read, write and admin, PII controls, and GDPR forget_entity with tombstones.
• Letta is an agent runtime in which the agent edits its own memory. Use it when you want the agent loop and its memory in one server. Brain is memory only: the agent stays in Claude Code, Cursor, Codex or your own code and reaches Brain over MCP (Streamable HTTP, or the stdio shim @inite/brain-mcp).
• Answers can abstain. synthesize ends each claim with the id of the fact it rests on, a verifier checks the support, and strict mode returns no answer rather than an unsupported one. Each fact keeps a pointer to the conversation or document it came from.
• No borrowed benchmark numbers. We do not set our memory-accuracy results against other systems' self-reported scores, which mostly use lenient judges. How we measure: docs/eval-protocol.md.

Part of the INITE Triad: Brain verifies the tokens INITE Auth issues, as INITE Billing does; the contract between them is the Triad contract. Run all three with one compose file: inite-ai/inite-triad.

What Brain is

Brain gives an agent memory between conversations: what was said, what changed, which entities are involved, and what supports an answer. A bitemporal graph stores structured facts and relationships; source episodes preserve context; scenes and beliefs capture events and evolving state. Domain Packs adapt that memory to a product's vocabulary and lifecycles without forking the engine.

Run Brain on your infrastructure or connect to the hosted service at brain.inite.ai. The web app provides memory search and exploration; REST and MCP provide the integration surface.

Why Brain

• Memory with its context. Retrieve structured facts, source passages and, when enabled, scenes and beliefs. Follow provenance back to the supporting conversation, document or evidence fragment.
• Changes stay inspectable. Facts carry valid time and knowledge time. Updates can supersede earlier facts; unresolved disagreements remain COMPETING. Retraction preserves history; administrative forgetting deletes associated records and leaves tombstones.
• A model of your domain. Packs define typed predicates, extraction guidance, scene schemas, state transitions, verification and retention hints, and optional media capabilities and MCP tools.
• Scope is explicit. Each tenant has a separate database. Personal memory uses userId; omitting it selects tenant-global memory. Key scopes, ABAC policies and PII controls further constrain access.
• Answers can be checked. Hybrid search, graph retrieval and multi-hop gather evidence. Synthesis cites it and runs verification; strict guardrails can abstain when support is insufficient.

Architecture

Brain separates source material, derived memory and the read path. This is a conceptual view; individual ingestion routes and retrieval profiles activate different parts of it.

flowchart LR
  input["REST / MCP<br/>conversations · documents · facts"]
  raw[("Source records<br/>documents · episodes · evidence")]
  derive["Indexers and scene builders<br/>candidates · entity resolution · conflicts"]
  memory[("Connected memory on SurrealDB<br/>facts + graph · scenes · beliefs")]
  retrieve["Retrieval<br/>semantic + lexical · graph · multi-hop"]
  answer["Synthesis + verification<br/>answer with citations or abstention"]
  packs["Domain Packs<br/>vocabulary · memoryModel · tools"]
  media["Evidence registration / upload<br/>scan hook · trusted processors"]
  input --> raw
  input --> derive
  media --> raw
  raw --> derive
  derive --> memory
  memory --> retrieve
  raw --> retrieve
  retrieve --> answer
  packs -. "domain configuration" .-> derive
  packs -. "capabilities and consent" .-> media

Rebuildable memory. Derived worlds can be rebuilt from retained episodes in a staging version. Readers stay pinned to the previous world until promotion. Scene maintenance can process dirty conversations on a schedule, with budgets, leases and metrics; it can compose scenes and promote supported beliefs.

Configurable retrieval. Retrieval profiles select mechanisms for the corpus and question. Semantic and lexical search, graph expansion, reranking, raw passages, scene retrieval and belief retrieval are distinct capabilities. A known entity can enter through graph_retrieve; a question spanning relationships can use search_multi_hop.

Separate serving and background work. The NestJS service uses a SurrealDB-backed job queue, leases and worker-thread offloads. Run the image as one process or split PROCESS_ROLE=api|worker; see the operations guide.

The code includes capabilities that are opt-in, not a promise that every installation runs every layer. Scene construction, scene serving, belief promotion, evidence upload/processing and pack projections have separate gates. Check the architecture, operations and flag definitions for scenes, evidence and pack projections when enabling them.

Domain Packs

A pack is a versioned JSON manifest installed per tenant. It tells the engine how to interpret a domain's material. Pack-derived observations remain candidates for the core pipeline to validate and resolve.

The industry pack library includes:

For example, real_estate declares the listing path listed → under_offer → sold, as well as withdrawal and return-to-market transitions. It distinguishes viewing and closing scenes, with an ephemeral retention hint for a viewing and a durable hint for a closing.

The built-in code_memory pack covers engineering decisions, rationale, invariants, gotchas and change lifecycles. Use record_decision, why and recall_decisions to retain the reasons behind the code. The six industry packs are distributable; built-in code memory is part of the core seed.

Author and distribute. Scaffold with pnpm pack:init my_pack, validate, optionally sign, publish to a registry and install per tenant. Registry versions are immutable, installs are checksum-pinned, and signature requirements follow the server's trust policy. Registry and marketplace support discovery, publisher profiles, mirroring and optional billing.

Consent is part of installation. The current first-party industry packs declare media capabilities, so installing them requires reviewing that section and passing --accept-modalities. This authorizes the declared capabilities; it does not supply a missing processor or enable every server feature. Pack MCP tools have a separate consent path. Built-in code_memory media declarations also do not, by themselves, activate media processing.

Full authoring, signing and installation commands: Domain Packs standard · MCP pack tools · pack evaluation.

Getting started

Use the hosted service

Hosted brain is provisioned per company: a tenant (companyId) and scoped API keys. Sign in and issue one on the keys screen — it shows the key once, alongside ready-to-paste configuration for Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI and Goose. If your workspace has not been provisioned yet, ask at info@inite.ai.

export BRAIN_URL="https://brain.inite.ai"
export BRAIN_KEY="brain_YOUR_API_KEY"

Keys can also be issued over the API by any credential you already hold — POST /v1/keys mints one no wider than the caller's own scopes, and POST /v1/keys/{id}/revoke takes it back. The same endpoints work on a self-hosted deployment, so the env-var key below is only ever a bootstrap.

Run from source

Prerequisites: Node.js 22, pnpm 10 and Docker Compose. The default model configuration needs an OpenAI API key. Local embeddings and alternative model providers are configuration choices; see operations.

git clone https://github.com/inite-ai/inite-brain-service.git
cd inite-brain-service
pnpm install --frozen-lockfile
cp .env.example .env
# Set OPENAI_API_KEY in .env for the default model configuration.

Create a local read/write key. This appends a generated key and its registration to your development .env; Brain authenticates against the SHA-256 hash.

node <<'JS'
const { randomBytes, createHash } = require('node:crypto');
const { appendFileSync } = require('node:fs');
const key = 'brain_' + randomBytes(24).toString('hex');
const keys = [{
  keyHash: 'sha256:' + createHash('sha256').update(key).digest('hex'),
  companyId: 'co_demo',
  scopes: ['brain:read', 'brain:write'],
}];
appendFileSync('.env', '\nBRAIN_KEY=' + key + '\nBRAIN_API_KEYS=' + JSON.stringify(keys) + '\n');
JS

docker compose up -d surrealdb
pnpm start:dev

In a second terminal, from the same directory:

export BRAIN_URL="http://localhost:3000"
export BRAIN_KEY="$(node --env-file=.env -p 'process.env.BRAIN_KEY')"
curl --fail-with-body "$BRAIN_URL/health"

For the full container setup, use docker compose --env-file .env up -d --build instead of pnpm start:dev. The app service publishes no host port — that is what lets --scale brain=N run several replicas — so copy docker-compose.override.yml.example to docker-compose.override.yml first; it maps host 3030, and BRAIN_URL=http://localhost:3030 then works for the requests below. The Compose defaults are for local development; production credentials and topology are covered in deployment.

Remember something, then ask about it

Text in, facts out. Brain captures the turn, extracts entities and claims, and runs each one through bitemporal conflict resolution:

curl --fail-with-body -X POST "$BRAIN_URL/v1/ingest/mention" \
  -H "Authorization: Bearer $BRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Maria moved to Berlin in June and prefers morning appointments.",
    "userId": "user_42"
  }'

curl --fail-with-body -X POST "$BRAIN_URL/v1/search" \
  -H "Authorization: Bearer $BRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "where does Maria live", "userId": "user_42", "limit": 5 }'

Use your application's stable user ID on both writes and reads. Omit userId on both only for tenant-global memory. The userId is also who is speaking: a first-person turn ("I moved to Berlin") lands on the user's own entity, and "where do I live?" on /v1/synthesize is answered to them. The memory learns the user's name from them — "I'm Maria" becomes a name fact on their own entity — or from your onboarding write: /v1/ingest/fact with entityRef: { "vertical": "user", "id": "user_42" }, predicate: "name", the same userId. (A speaker anchor { "vertical": "user", "id": "user_42", "role": "speaker", "name": "Maria" } on a mention names them too.) To relay someone else's words under the user's scope, anchor that person as the speaker instead. Until a name is learned, workspace_status and /v1/users/:userId/profile say so — ask once, record it.

Record a fact you already know

When the claim is already structured — a CRM field changed, an event fired — skip the extractor and state it. The response says what the resolver decided (INSERTED, SUPERSEDED, COMPETING…), not just that the write happened:

curl --fail-with-body -X POST "$BRAIN_URL/v1/ingest/fact" \
  -H "Authorization: Bearer $BRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityRef": { "vertical": "rent", "id": "cust_42" },
    "predicate": "complained_about",
    "object": "late maintenance",
    "validFrom": "2026-09-01T10:00:00Z",
    "userId": "user_42",
    "source": { "vertical": "rent", "messageId": "msg_1" }
  }'

The local key above has no administrative scope; pack installation and forgetting require an appropriately scoped operator key. More: getting started.

Connect an agent

Claude Code — one command

/plugin marketplace add inite-ai/inite-brain-service
/plugin install inite-brain@inite

That installs the MCP server, the six skills, and the lifecycle hooks together: SessionStart injects what Brain already knows about the repo you are in, PreCompact and SessionEnd write the session back. Claude Code prompts for your API key at enable time and keeps it in the OS keychain. Details and switches: plugin README.

Prefer to wire it by hand?

claude mcp add --transport http brain https://brain.inite.ai/mcp \
  --header "Authorization: Bearer $BRAIN_KEY"

Gemini CLI — one command

export BRAIN_API_KEY="brain_..."
gemini extensions install https://github.com/inite-ai/inite-brain-service

MCP server, the six skills, and the agent memory guide loaded as context. The key stays in your environment — the manifest references ${BRAIN_API_KEY} and Gemini expands it at connect time.

Cursor and VS Code — one click

Those two publish an install URL scheme, so the badges at the top of this file do the work; replace the placeholder key in the client's own MCP settings afterwards. Every other client takes the URL https://brain.inite.ai/mcp (or ?tools=chatgpt for ChatGPT, whose connector contract is exactly search + fetch).

Every other harness

curl -fsSL https://brain.inite.ai/install.sh | sh

Installs the skills into every agent it finds on the machine — Claude Code, Codex CLI, Gemini CLI, openclaw, opencode — and takes --target cursor,agents --scope project for the project-local ones. SKILL.md is a cross-agent format, so the same six skills work unchanged everywhere.

For clients that launch a stdio MCP server, use the first-party @inite/brain-mcp connector. This configuration fits clients with a mcpServers map, including Claude Desktop:

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["-y", "@inite/brain-mcp"],
      "env": {
        "BRAIN_API_KEY": "brain_YOUR_API_KEY",
        "BRAIN_COMPANY_ID": "YOUR_COMPANY_ID"
      }
    }
  }
}

For the local setup, use company ID co_demo, the key from .env, and add "BRAIN_BASE_URL": "http://localhost:3000" to env (port 3030 for Compose). Node.js and npx must be available to the client.

Clients with native remote MCP support can connect directly over Streamable HTTP:

URL: https://brain.inite.ai/mcp          (tenant taken from the credential)
     https://brain.inite.ai/mcp/<companyId>   (explicit, must match the key)
Authorization: Bearer brain_<api-key>

Both spellings serve the same endpoint. Use the tenant-less one when the client only knows a URL — that is every OAuth-discovered connector, where the tenant arrives in the token's org claim rather than from the person pasting the config. An unauthenticated probe answers at /mcp/health (and /mcp/<companyId>/health), so a setup script can check reachability before any credential exists.

The key's scopes determine available tools; server flags and installed packs can extend the surface. The connector forwards tools and resources, and bridges MCP sampling when the client supports it. See the per-client setup guide.

Read the agent memory guide for memory semantics and the skills guide for reusable agent workflows. Synthesis keeps fact references in citations and other evidence references (episodes, fragments, scenes and beliefs) in evidenceCitations; preserve both when presenting an answer.

Build with the SDK

npm install @inite/brain

import { createBrain, brainTools } from '@inite/brain'

const brain = createBrain({ apiKey: process.env.BRAIN_KEY!, userId: 'user_42' })
await brain.remember('Maria moved to Berlin in June.')
const { answer, citations } = await brain.answer('where does Maria live')

brainTools(brain) returns tool definitions the Vercel AI SDK takes directly, and createBrainStore(brain) is a LangGraph-shaped store over the same memory. One dependency (zod), no framework required: @inite/brain.

Using Anthropic's memory tool (memory_20250818)? Swap the filesystem backend for a tenant-fenced service without touching your agent loop: @inite/brain-memory-tool.

Feed it documents

Enable DOCUMENT_INGEST_ENABLED=1 on the server. Submit normalized text through Source → Indexer → Candidates → Brain:

curl --fail-with-body -X POST "$BRAIN_URL/v1/ingest/document" \
  -H "Authorization: Bearer $BRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "markdown",
    "title": "Acme maintenance review",
    "text": "Customer cust_42 reported late maintenance. The team agreed to review response times next week.",
    "occurredAt": "2026-09-01T10:00:00Z",
    "userId": "user_42",
    "contextRef": { "vertical": "rent" }
  }'

Indexers stage candidates before the core resolves and commits facts. Stored content can be re-indexed after installing a new pack; external indexers can join over a pull work API. storeContent: false disables content retention for that document, so later re-indexing cannot reuse its text. Document pipeline · External indexers.

Or let the brain read what already exists: a folder, a bucket, a site, an MCP server — install a source pack (file_memory, web_memory), connect a source in Admin → Connections, sync; every fact carries the file's revision. For what lives on a laptop, a CI runner or a box on the LAN, the @inite/brain-agent walks it there — folders, a repository's committed docs, a local MCP server — and the brain keeps the books. Source plane.

Files and evidence

The evidence plane supports metadata/reference registration through POST /v1/ingest/evidence-asset and multipart blob upload through POST /v1/ingest/evidence-blob. Uploaded assets pass a scan hook and can be dispatched to trusted processors; outputs are derived representations, with fragment locators where supplied by the processor.

Current adapters include local image metadata decoding, PDF text-layer extraction and plain-text extraction. Image metadata is not visual scene understanding; PDF text extraction is not OCR. A modality declared by a pack is a capability request, not proof that a corresponding audio, video or vision processor is installed.

These paths require their evidence gates, storage configuration and applicable pack consent. Raw serving additionally checks scope and PII policy. Evidence contracts · Evidence configuration · Processor adapters.

Build on Brain

• Extend the domain: author a pack, publish to the registry and install a reviewed version per tenant.
• Connect an indexer: use the pull protocol and reference client.
• Extend the agent: declare pack MCP tools, with separate consent for the added tool surface.
• Inspect the API: OpenAPI 3.1 is generated with pnpm openapi:build from the platform contracts.

Quality and evaluation

Retrieval, answer accuracy and state-transition correctness measure different things. Published scores belong to a particular dataset, reader model, retrieval profile, token budget and code revision; they are not a general accuracy guarantee for the running service.

Conversational-memory results use a strict binary judge, our own full-context baseline, paired statistics and a held-out split. Read the evaluation protocol and methodology alongside any reported number; scores published under different protocols are not directly comparable.

CI: PRs run lint, formatting, type checking, builds, unit tests with coverage, socket and integration tests, plus frontend checks and supply-chain checks. The real-LLM quality eval runs nightly or by manual dispatch, not on every PR. The workflow is the source of truth: .github/workflows/ci.yml.

Battery guides: memory fitness · state transitions · domain packs · code memory.

Stack

Node.js 22 · NestJS · TypeScript · SurrealDB 3.x · configurable embedding and LLM providers · local BGE-M3 option · configurable reranking · SurrealDB-backed jobs and leases · worker threads · OpenTelemetry. The web app and docs use Next.js, React and Tailwind CSS.

Documentation

Documentation hub · Web docs, EN/RU

Contributing

Contribute with an AI agent

You don't need to be an engineer. Open the repo (Codespaces above gives a ready environment with SurrealDB running), start your coding agent and describe the idea in plain words:

• Claude Code: /contribute — it restates the idea, writes a short spec, builds it with tests, runs the gates and opens a PR. /spec-idea only files the idea as an issue.
• Any other agent (Cursor, Codex, Copilot, Gemini CLI, Windsurf…): "Read AGENTS.md and help me add …".

AGENTS.md is the source of truth for agents: commands, zones (what is safe to change and what needs a maintainer first) and the idea → PR loop. Prefer to just propose? Use the Product idea form.

The workflow

See CONTRIBUTING.md for the workflow and CODE_OF_CONDUCT.md for community guidelines.

pnpm lint:ci
pnpm format:check
pnpm typecheck
pnpm build
pnpm test
pnpm test:socket
# Integration suites require Docker:
pnpm test:e2e
pnpm test:e2e:jobs

Choose additional evals for the behavior you change; real-model runs require provider credentials. Database changes belong in new numbered migrations in src/db/migrations/. For vulnerability reports, follow SECURITY.md.

Roadmap

Follow issues and releases for current work. Design notes and earlier experiments remain in docs/roadmap; read their dates and status before treating an item as shipped or pending.

License

AGPL-3.0-or-later.