Generates embeddings for stored memories against an OpenAI-compatible /v1/embeddings endpoint (768 dimensions by default), which powers the vector half of hybrid retrieval.
Uses PostgreSQL with the pgvector extension as the memory store: thoughts, decisions, session events, repo facts and contacts are written through ordered migrations and retrieved with hybrid search that fuses pgvector similarity and PostgreSQL full-text rankings via reciprocal rank fusion. Also covers maintenance jobs (distillation into candidates, DREAM stages) plus backup and restore scripts with verification.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Open Brain search my memory for the decision about the auth refactor"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Shared, scoped long-term memory for AI agents, served as an MCP server over PostgreSQL and pgvector.
Architecture of the actual components. Open Brain has no hosted UI to screenshot; the local grading page needs a live database.
Open Brain stores what AI agents learn (thoughts, decisions, session events, repo facts, contacts) in PostgreSQL with pgvector, and serves it back through versioned MCP tools with hybrid retrieval: vector similarity plus full-text search, fused with reciprocal rank fusion (RRF). Claude Code and Codex session hooks capture work as it happens, and a typed Python client and a TypeScript client talk to the same contract.
Related MCP server: butler-memory-mcp
Coding agents forget everything between sessions. When several agents work for one person, each one also relearns what the others already found. Open Brain is the one place those agents write to and read from, with three properties a plain vector store does not give you:
Scope and identity. Every caller has a bearer token mapped to a role (admin, agent, readonly, promoter, and others). Memory lives in namespaces, and a context pack only returns items whose agent, platform, channel and session scope match exactly.
A contract, not a tool list. get_contract publishes the tool surface,
input schemas and a schema hash. Clients declare the contract they were
built against instead of hard-coding tool names.
Nothing becomes durable on its own. Captured conversation turns are
distilled into candidates. A candidate becomes memory only after it is
graded, by a person on the grading page (docs/grading-page.md) or by an
explicit promotion rule.
See the diagram above. Session hooks in python/openbrain and
python/openbrain-provider send events through python/openbrain-memory,
the only Python write path, to the server over HTTP with a bearer token. The
server (server/) authenticates the token, resolves the namespace, and runs
the requested tool: capture, raw-turn ingest, session events, search or an
agent context pack. Search combines a pgvector similarity query with
PostgreSQL full-text search and fuses the two rankings with RRF. Background
jobs in server/maintenance distill raw turns into candidate_memory and
run the DREAM stages (light, REM grading, deep), and the grading page is
where a person promotes or rejects each candidate.
MCP server over Streamable HTTP, with a REST surface and an optional NATS request/reply transport.
Hybrid retrieval: vector plus full-text search fused with RRF, and a budgeted context-pack builder for session start.
Role-based access per bearer token, with namespace and scope isolation.
A published, hashed contract (get_contract) and recorded fixtures in
contracts/ that pin it.
Session capture hooks for Claude Code and Codex, with a local spool so a network failure does not lose a turn.
Distillation of raw turns into candidates, and a keyboard-driven grading page to promote or reject them.
Ordered SQL migrations, backup and restore scripts with verification, and
retrieval evaluations in eval/.
Example Kustomize manifests in k8s/ (registry and hostnames are
placeholders).
Path | What it is |
| The MCP server (Node 24, TypeScript, |
| The schema, as ordered SQL migrations. |
| Migration runner, backfill, curation, distillation and DREAM stages, backup and restore, the grading server. |
| Python client library and CLI ( |
| Session-capture hooks for Claude Code and Codex. |
| Context-budget and policy gates used by those hooks. |
| TypeScript client. |
| Recorded request/response fixtures that pin the public contract. |
| Retrieval and context-pack evaluations. |
| An agent skill that teaches a model how to use the tools. |
| Architecture, configuration reference, contracts and design notes. |
Requirements: Node.js 24, PostgreSQL 13 or later with the vector
extension, and an OpenAI-compatible /v1/embeddings endpoint (768
dimensions by default).
git clone https://github.com/rodaddy/open-brain.git
cd open-brain
npm ci
cp .env.example .env # fill in DB_*, EMBEDDING_* and AUTH_TOKEN_* values
psql -c 'CREATE EXTENSION IF NOT EXISTS vector;' # once, against your database
npm run migrate
npm start # serves MCP on PORT (default 3100)Generate each auth token with openssl rand -hex 32. Every environment
variable and the client configuration are in docs/README.md and
docs/CONFIG_REFERENCE.md.
Tests:
npm test # unit tests; database suites fail fast without one
npm run test:isolated # whole suite against a fresh, throwaway database
cd python/openbrain-memory && uv run pytestSuites named *.pg.test.ts, *.live.test.ts and a few script tests need a
real Postgres (OPENBRAIN_TEST_DATABASE_URL); npm run test:isolated
creates one, migrates it, runs everything and drops it.
The repo is MIT licensed: use it, change it and ship it, keeping the copyright notice.
Open Brain went from a one-day v1 (2026-03-13) to 668 commits over seven months, built by AI coding agents under one operator's direction. Each phase was planned, built test-first and checked by an agent review swarm; later work ran as numbered lanes whose acceptance claims are scripts that must pass. Notable turns: an isolated-database test run became the default after shared-database runs gave different failure counts on unchanged code, and a batch of merges was reverted when one rested on an untested claim. The full account, with dates, design decisions and what did not work, is in docs/BUILD-STORY.md.
Active, single-operator deployment.
In daily use by one operator. The server, the Python client and the Claude Code and Codex capture hooks run every day on one person's machines and home lab, for a handful of agents. It has not been run multi-tenant or at scale.
Built and tested, lightly used: the NATS transport, the DREAM stages, the grading page, and the backup and restore drills.
Design only: several documents under docs/ describe designs that are
not built. Each says so in its status line.
Paths such as /srv/dev and hostnames such as *.example.internal in docs
and tests are placeholders.
There is no CI configuration in this snapshot; the original ran on self-hosted runners that are not part of this repo.
What it does not do: it is not a hosted service, it does not decide what is worth remembering for you (capture is broad, promotion is deliberate), and it does not ship an embedding model.
Ideas, not code, from prior memory systems; each is recorded with what was
taken and why in docs/prior-art/ATTRIBUTION.md:
Graphiti for the bi-temporal fact model.
Cognee,
mem0, Honcho and GBrain, reviewed in
docs/prior-art/.
pgvector and the Model Context Protocol.
Rico Rojas, https://rico-rojas.com
Licensed under the MIT License. See LICENSE.
This server cannot be deployed
Shared cross-LLM long-term memory over MCP: semantic recall, sessions, and media (pgvector).
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Memory for AI agent teams across tools, sessions, repositories, and teammates.
Versioned agent memory in your own Postgres: portable context, permissioned, audit trail.
