myco-brain

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/myco-logo-dark.png">
    <img src="./docs/assets/myco-logo.png" alt="Myco Brain" width="340">
  </picture>
</p>

**Persistent, source-traceable memory for AI agents — self-hosted on your own Postgres, with no API keys required to run.**

[![CI](https://github.com/thegoodguysla/myco-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/thegoodguysla/myco-brain/actions)
[![npm](https://img.shields.io/npm/v/@mycobrain/mcp-server)](https://www.npmjs.com/package/@mycobrain/mcp-server)
[![LongMemEval](https://img.shields.io/badge/LongMemEval_oracle-73.6%25_QA-blue)](./evals/longmemeval/README.md)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)

![Watch it remember — save, ask days later, recall with provenance](./demos/media/watch-it-remember.gif)

- **Source-traceable.** Every fact traces to the document it came from (`brain_why`) — no trust-me summaries.
- **Trust that compounds.** Independent corroboration _raises_ a fact's confidence; a contradiction _supersedes_ it — kept and audited, never silently overwritten.
- **Keyless & local-first.** Full-text + semantic search and the knowledge graph all run with zero hosted dependency — add an Anthropic key only for the most accurate graph.
- **Yours.** Apache-2.0, plain Postgres tables, 11 MCP tools. Works with Claude, Cursor, Windsurf, Continue, Zed.

**Who it's for:** **dev teams** running agents that need one shared memory · **agencies** needing hard per-client isolation · **anyone** who wants their assistant to remember across sessions — import your ChatGPT / Claude history and your AI knows you on day one.

_Built solo by a growth marketer — not a career engineer — directing AI coding agents over ~3 months. [How it was built ↓](#who-built-this)_

The usual fix for agent amnesia — letting an LLM maintain its own memory —
fills it with duplicates, hallucinated summaries, and confident answers nobody
can trace. Myco Brain is built on the opposite contract:

> **The LLM proposes. Deterministic rules decide what becomes a fact. You set
> the bar** — from corroboration-gated auto-promotion (the default) to strict
> human review of every fact (`BRAIN_REQUIRE_HUMAN_REVIEW=1`).

Claude, Cursor, Windsurf, Continue, Zed, and custom agents all share one memory
backed by your own Postgres.

⭐ If the trust model resonates, a star helps others find it.

```bash
# 1. Boot the stack (Postgres + MCP server + extraction worker)
git clone https://github.com/thegoodguysla/myco-brain.git && cd myco-brain
docker compose up -d

# 2. Give your agent a memory — point it at any repo or folder
#    (no env needed: it finds the quickstart stack on localhost)
npx -y -p @mycobrain/mcp-server mycobrain-ingest github:your-org/your-repo

# 3. Connect your client (one-liner below), then ask across sessions:
#    "what did we decide about auth, and where is that documented?"
#    → answered from your docs, with the source cited.
```

> [!TIP]
> **Zero API keys, all the way down.** Full-text search, semantic search (local
> embeddings), and the knowledge graph (local extraction) all run with no hosted
> dependency. Add an Anthropic key only if you want the most accurate graph.

**MCP-native by design — your agent knows _when_ to use memory, not just _how_.**
Most MCP servers expose tools and hope the model calls them. Myco ships a usage
contract over MCP's `instructions` channel: the moment it connects, your agent
knows to pull context before a task, save durable decisions, and cite sources
with `brain_why` — no per-project prompting. Tune the policy in one copy-paste
block: [Teach your agent to use it well](./docs/agent-setup.md).

Quick links:
[10-minute quickstart](#get-started-in-under-10-minutes) ·
[Teach your agent to use it well](./docs/agent-setup.md) ·
[The trust engine](#memory-that-gets-more-trustworthy-compounding-confidence) ·
[Benchmark — run it yourself](#benchmark--run-it-yourself) ·
[Run every proof](#every-claim-has-a-check) ·
[Who it's for](#who-its-for) ·
[Environment variables](#environment-variables) ·
[Architecture](#architecture) ·
[Roadmap](./ROADMAP.md) ·
[Cloud waitlist](#cloud-waitlist)

## Memory that gets more trustworthy (compounding confidence)

Most agent memory **overwrites** facts silently. Myco Brain **compounds** them:

![Compounding confidence — corroboration raises, contradiction supersedes](./demos/media/compounding-confidence.gif)

- An independent source agreeing with a fact **raises** its confidence
  (damped noisy-OR — ten chunks of one document corroborate nothing; only
  distinct sources count).
- A confident contradiction on a single-valued relationship (who you *work
  for*, where something *is located*) **supersedes** the old fact: it's
  closed and weakened — **kept, never deleted** — with the supersession
  recorded in an audited claims ledger.
- Ask `brain_why` about any fact and you get its **distinct** source count (per
  relationship, not per mention), its confidence trend over time ("0.8 → 0.86"),
  and any superseded history.
  Contradictions stay visible. Your memory can't gaslight you.

```text
works for → Halcyon Labs           0.55  [SUPERSEDED — kept, not deleted]
works for → Driftwood Analytics    0.90  [ACTIVE]
claims ledger: old fact superseded_by → new fact (audited)
```

*Proof: `npm run test:compounding` — the full lifecycle runs against a live
database in seconds, no LLM required.*

## The schema evolves with your data (dynamic schema)

- The extraction worker notices entity kinds and relationship types your catalog
  doesn't have yet and **proposes** them (`brain_stats`: *"Brain proposed 3 new
  types from your data"*).
- **Promotion is yours by default** — or opt into auto-promotion for types
  corroborated across enough **distinct source documents**
  (`BRAIN_SCHEMA_AUTO_PROMOTE=1`), counted per document, not per mention, so two
  documents passed back and forth can't manufacture consensus. One chatty
  document can never promote anything.
- A promoted type stays **scoped to the workspace that earned it** — one client's
  vocabulary never leaks into another's catalog (see
  [per-client isolation](#one-isolated-workspace-per-client--built-for-agencies)).

*Proofs: `npm run test:dynamic-schema`, `npm run test:schema-promotion`.*

**You pick the trust dial:**

| Mode | Behavior |
|---|---|
| Default | Confident facts auto-promote; novel types wait for review |
| `BRAIN_REQUIRE_HUMAN_REVIEW=1` | **Strict curation** — nothing the LLM proposes touches the canonical graph without a human decision |
| `BRAIN_SCHEMA_AUTO_PROMOTE=1` | Corroborated new types promote themselves, audited |

When something is waiting on you — novel types in default mode, or everything
in strict mode — review it from the command line:

```bash
mycobrain review                 # list pending entities, relationships, types
mycobrain review approve <id>    # promote it into the graph
mycobrain review reject  <id>    # reject it (kept and audited, never deleted)
```

*Proof: `npm run test:review` — approving actually lands the entity / edge /
type in the canonical graph; rejecting never does.*

## Private memories, shared knowledge

Multi-agent teams get real isolation: documents marked `private` are readable
**only by the agent that created them** — enforced in every read tool, on top
of workspace row-level security. Workspace memory stays shared. *Proof:
`npm run test:sharing` (a two-agent visibility matrix).* Like workspace
isolation, it binds only under the least-privilege `brain_app` role
([security note](#one-isolated-workspace-per-client--built-for-agencies)).

## One isolated workspace per client — built for agencies

Put each client in their own workspace, share one agency-wide playbook, and
the guarantee you sell is **Postgres row-level security** — a session scoped
to Client A cannot return Client B's rows. The
[agency starter kit](./examples/agency/) provisions it (one command) and ships
the least-privilege DB role that makes the isolation actually bind. *Proof:
`npm run test:agency` — Client A sees zero of Client B's facts.*

> [!IMPORTANT]
> **Isolation binds only under the least-privilege role.** RLS does not constrain
> a Postgres **superuser**, and the zero-config quickstart's default `brain` role
> *is* a superuser (fine for a single-workspace self-host — there's nothing to
> isolate). Before you put more than one client in one database, run the app as
> the `NOSUPERUSER` `brain_app` role the agency kit ships; `mycobrain-doctor`
> flags a superuser connection. Multi-tenant isolation is a guarantee of
> `brain_app`, not of the default quickstart role.

<details>
<summary><strong>Advanced — multi-tenant gateways: who is the caller? (<code>BRAIN_TRUST_REQUEST_IDENTITY</code>)</strong></summary>

<br>

RLS decides *which rows a tenant can read*; this setting decides *which tenant a
request is* — the step before RLS. On the **stdio** server, identity is taken
**only from the server's environment** by default: a `workspace_id`, `agent_id`,
or `api_key` supplied in tool-call arguments is **ignored**, so even a
prompt-injected agent can't pass `workspace_id: "<someone-else>"` to reach
another workspace. (For `brain_` keys, identity comes from the key string and
nothing else.)

Set `BRAIN_TRUST_REQUEST_IDENTITY=1` **only** when you front the server with a
real multi-tenant gateway that authenticates each request and maps it to a
tenant itself — then per-request identity is honored (and a service-role JWT
must **equal** `BRAIN_SERVICE_ROLE_KEY`, not merely look like one). **Single-tenant
self-hosts need none of this** — their identity is already environment-derived.

</details>

## Query over HTTP (read-only)

Not everything speaks MCP. For a web app, an automation, or a partner backend,
`mycobrain-r