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.</b><br>
  Facts, conversations, events and their evidence — connected across sessions.<br>
  Temporal history, domain memory models and grounded answers over REST and MCP.
</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="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://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/TypeScript-3178c6.svg" alt="TypeScript">
  <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="#architecture">Architecture</a> ·
  <a href="#domain-packs">Domain Packs</a> ·
  <a href="#quick-start">Quick start</a> ·
  <a href="https://brain.inite.ai/en/docs">Docs</a> ·
  <a href="AGENTS.md">Agent guide</a>
</p>

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](https://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.

```mermaid
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](docs/operations.md#splitting-api-and-worker-roles).

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](docs/architecture.md), [operations](docs/operations.md)
and flag definitions for [scenes](src/common/scene-flags.ts),
[evidence](src/common/evidence-flags.ts) and
[pack projections](src/common/pack-projection-flags.ts) 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`, `evalFixtures` | Domain instructions, examples and extraction checks. |
| `memoryModel` | Scene schemas, state models and transitions, attention hints, verification rules and advisory retention hints. Also declares supported modalities, requested processor capabilities and raw-evidence policy. |
| `indexer`, `seedDocuments` | Participation in document indexing and knowledge supplied with the pack. |
| `mcpTools` | Additional agent tools, subject to explicit operator consent. |

The [industry pack library](packs) includes:

| Pack | Example memory models |
| --- | --- |
| [`real_estate`](packs/real-estate.pack.json) | Listings, tenancies and permits. |
| [`fintech`](packs/fintech.pack.json) | Licenses and certifications. |
| [`medical`](packs/medical.pack.json) | Drug ontology, prescription and approval lifecycles. |
| [`legal`](packs/legal.pack.json) | Agreements, obligations and legal matters. |
| [`insurance`](packs/insurance.pack.json) | Policy and claim lifecycles. |
| [`hr`](packs/hr.pack.json) | Positions and employee lifecycles. |

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`](src/ai/domain-packs/code-memory.pack.ts) 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