OpenBrain is an open-source machine-readable memory layer for agentic systems.
It stores typed, versioned memory objects (claims, decisions, tasks, artifacts, entities, relations, thought summaries), supports structured queries + semantic search, and exposes a standard plug-in protocol via MCP (and a mirror HTTP API).
Goal: stop context switching / context rot by moving memory out of provider silos (ChatGPT/Codex/Claude/Gemini/local models) into an agent-owned infrastructure plane.
NOTE (Do not edit without explicit instruction):
The header + hero lines above and the License/footer at the end of this README are considered project identity text.
Please refrain from changing them unless explicitly instructed by the project owner. Contributors: Richard Infantado (richard.infantado@gmail.com), Robert Leroux (rl.isapience@gmail.com)
Most agent stacks still keep memory trapped inside provider-specific context windows. That makes state fragile, hard to audit, and difficult to share across models. OpenBrain exists to separate memory from model runtime: the model becomes a stateless compute adapter, while OpenBrain is the durable state plane with typed records, deterministic retrieval, and governance boundaries.
OpenBrain organizes memory by workspace (scope), which is the top-level isolation boundary for data and policy. Each workspace has ownership semantics and role-based access controls.
Objects are typed memory records with versioned updates. Events are append-only facts about how those objects changed, who changed them, and when. Embeddings are stored in separate spaces keyed by provider, model, and kind, so the same object can be represented in multiple semantic spaces without changing vector dimensions.
Lifecycle and conflict metadata are first-class. Objects can move through scratch, candidate, accepted, and deprecated, with TTL defaults and explicit expiry. Keyed memories use memory_key plus deterministic value_hash to mark conflicting values and capture resolution metadata.
Default retrieval is strict: only accepted and non-expired objects are returned. This applies to scoped reads, structured search, and semantic search.
Clients can opt in to broader views using optional request fields:
include_statesinclude_expirednow(for deterministic evaluation)
Semantic search can target a specific embedding space with embedding_provider, embedding_model, and embedding_kind. Governance still applies at read time: policy and role checks can deny or clamp requests even when the client asks for broader access.
Workspaces are owned and governed. Ownership controls administrative actions such as token and policy management, while writer/reader roles control day-to-day memory operations.
Auditability is built on immutable event history and timeline queries. Retention boundaries are policy-driven through policy.retention objects that define default TTLs, maximum TTL caps, and immutable kinds. These boundaries are enforced on write/update so retention decisions are deterministic and workspace-owned.
When access is denied, responses include explainability fields (reason_code and policy_rule_id) so operators can understand which policy blocked the action without exposing sensitive data.
MCP stdio is the primary integration path for agent runtimes.
Core capabilities:
openbrain.pingopenbrain.writeopenbrain.readopenbrain.search.structuredopenbrain.embed.generateopenbrain.search.semantic
Governance capabilities:
openbrain.workspace.infoopenbrain.audit.object_timelineopenbrain.audit.memory_key_timelineopenbrain.audit.actor_activity
Optional enrichment capabilities:
openbrain.rerankopenbrain.memory.pack
HTTP mirrors the MCP surface and is designed for local debugging, service composition, and SDK usage.
Core endpoints:
/v1/ping/v1/write/v1/read/v1/search/structured/v1/embed/generate/v1/search/semantic
Governance endpoints:
/v1/workspace/info/v1/audit/object_timeline/v1/audit/memory_key_timeline/v1/audit/actor_activity
Optional enrichment endpoints:
/v1/rerank/v1/memory/pack
- Start Postgres with
pgvector, then setDATABASE_URL. - Start OpenBrain HTTP locally:
openbrain serveDefault local binary port is http://127.0.0.1:7981. If you use Docker Compose onboarding, the mapped app port is http://127.0.0.1:8080 (including /viewer).
3. Authentication:
- HTTP uses
Authorization: Bearer <token> - MCP passes
auth_tokenduring initialize
OpenBrain ships TypeScript and Python SDKs with both an HTTP client and an MCP helper:
sdk/typescript/openbrain-sdksdk/python/openbrain_sdk
TypeScript:
import { OpenBrainHttpClient } from "@openbrain/openbrain-sdk";
const client = new OpenBrainHttpClient({ baseUrl: "http://127.0.0.1:7981" });
await client.ping();
const matches = await client.searchSemantic({ scope: "workspace:demo", query: "release policy", top_k: 3 });
console.log(matches.matches.length);Python:
from openbrain_sdk import OpenBrainHttpClient
from openbrain_sdk.models import SearchSemanticRequest
client = OpenBrainHttpClient(base_url="http://127.0.0.1:7981")
client.ping()
result = client.search_semantic(SearchSemanticRequest(scope="workspace:demo", query="release policy", top_k=3))
print(len(result.matches))The terminal UX focuses on inspectability and fast policy debugging. openbrain workspace info shows ownership and current caller role, openbrain audit object|key|actor provides bounded timelines, and openbrain retention show displays the effective retention policy. When a command is denied, CLI output surfaces explainability directly as reason_code plus policy_rule_id.
OpenBrain keeps local quality gates deterministic with a single entrypoint:
scripts/ci/quality-gates.ps1(Windows)scripts/ci/quality-gates.sh(Unix) Trademark and branding policy: seeTRADEMARK.md.
The gate runs formatting, clippy, tests, cargo deny, and gitleaks checks. Live-network tests are opt-in only via explicit RUN_* flags and are forced off in the quality gate flow.
OpenBrain is now governed and auditable in terminal-first workflows; next work is about visibility and compliance ergonomics on top of the same policy engine and event trail.
- Governance UX enhancements on top of the existing read-only
/viewersurface - Compliance pack with tamper-evident event exports and redaction policy tooling
- MCP-over-HTTP transport for broader deployment patterns
Apache-2.0 (recommended for wide adoption) or MIT.
Digilabs Company Australia © NYEX AI Platform. All rights reserved. AIC Pty Ltd (ACN 082 378 256)