inite-brain-service

<p align="center"> <a href="https://brain.inite.ai"> <img src="https://brain.inite.ai/api/og?title=Memory%20with%20context&kind=brand" alt="INITE Brain — memory with context" width="100%"> </a> </p> <h1 align="center">INITE Brain</h1> <p align="center"> <b>Open-source memory for AI agents: a bitemporal knowledge graph with provenance, over MCP and REST.</b> </p> <p align="center"> <a href="https://github.com/inite-ai/inite-brain-service/actions/workflows/ci.yml"><img src="https://github.com/inite-ai/inite-brain-service/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/inite-ai/inite-brain-service/releases/latest"><img src="https://img.shields.io/github/v/release/inite-ai/inite-brain-service?sort=semver&label=release&color=8b5cf6" alt="Latest release"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg" alt="License: AGPL-3.0-or-later"></a> <a href="https://hub.docker.com/r/mikefluff/inite-brain-service"><img src="https://img.shields.io/docker/pulls/mikefluff/inite-brain-service" alt="Docker pulls"></a> <a href="https://hub.docker.com/r/mikefluff/inite-brain-service/tags"><img src="https://img.shields.io/badge/image-arm64%20%7C%20amd64-2496ed.svg" alt="Image: arm64 | amd64"></a> <a href="https://github.com/inite-ai/inite-brain-service/stargazers"><img src="https://img.shields.io/github/stars/inite-ai/inite-brain-service?style=flat" alt="Stars"></a> <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome"></a> <img src="https://img.shields.io/badge/MCP-native-ffb938.svg" alt="MCP native"> </p> <p align="center"> <a href="https://brain.inite.ai/en/app/keys"><img src="https://img.shields.io/badge/Claude%20Code-%2Fplugin%20install-d97757.svg" alt="Install in Claude Code"></a> <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=brain&config=eyJ1cmwiOiJodHRwczovL2JyYWluLmluaXRlLmFpL21jcCIsInRyYW5zcG9ydCI6Imh0dHAiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgYnJhaW5fWU9VUl9BUElfS0VZIn19"><img src="https://img.shields.io/badge/Add%20to-Cursor-000000.svg" alt="Add to Cursor"></a> <a href="vscode:mcp/install?%7B%22name%22%3A%22brain%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fbrain.inite.ai%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20brain_YOUR_API_KEY%22%7D%7D"><img src="https://img.shields.io/badge/Add%20to-VS%20Code-0098ff.svg" alt="Add to VS Code"></a> <a href="https://registry.modelcontextprotocol.io/v0/servers?search=inite-brain"><img src="https://img.shields.io/badge/MCP%20Registry-io.github.inite--ai-ffb938.svg" alt="MCP Registry"></a> </p> <p align="center"> <a href="https://brain.inite.ai">Website</a> · <a href="#quick-start">Quick start</a> · <a href="#architecture">Architecture</a> · <a href="#domain-packs">Domain Packs</a> · <a href="#getting-started">Getting started</a> · <a href="https://brain.inite.ai/en/docs">Docs</a> · <a href="docs/agents-using-brain.md">Agent guide</a> </p>

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

| Memory layer | What it preserves | | --- | --- | | Facts and entities | Typed claims, canonical entities, relationships, confidence, source attribution and temporal history. | | Episodes | Source turns and conversation context that derived memory can point back to or be rebuilt from. | | Scenes | Bounded events with gists, entities, state changes and source links. Optional gist embeddings and a scene retrieval lane make them searchable alongside other evidence. | | Beliefs | Derived state with revision history and supporting scenes. Pack-projected state deltas can feed belief promotion. | | Evidence | Assets, located fragments, processing runs and derived representations, with links to the memories they support. |

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.

| A pack can declare | Purpose | | --- | --- | | predicates | Typed vocabulary, value constraints, conflict semantics, decay and PII classes. | | extractionProfile, `evalFi