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>

**Shared memory for your AI agents, on your own Postgres. Every fact keeps its source, a change supersedes the old fact instead of overwriting it, and each client's facts stay inside that client's boundary.**

[![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-73.6%25_QA_·_recall@5_89--92%25-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)

## Memory for your agents in two commands

```bash
npm install -g @mycobrain/mcp-server
mycobrain-setup memory
```

You need Node.js 20 or later. Setup asks a few questions, shows each file it is
about to change, and waits for a yes. It backs up every file it edits, writes no
secret into any of them, and finishes by writing one fact and reading it back.
`mycobrain-setup memory --uninstall` removes what it added.

- **Where the memory lives.** A local Postgres with pgvector: setup finds one on
  your machine or starts one in Docker. Or give it any Postgres connection
  string (Supabase, Neon, RDS, self-hosted) by reference, so the string never
  lands in your shell history.
- **Starter templates.** Agency, design studio, architecture or landscape firm,
  solo consultant, or `custom`, a short interview that writes a template for
  your own business. A template sets how clients are split into houses, the kinds
  of entities, and what is worth remembering.
- **Automatic in Claude Code and Codex.** Hooks recall the relevant facts at
  session start and before every prompt. A background worker reads each finished
  session and files the durable facts it finds.
- **Over MCP in Cursor, Windsurf and Claude Desktop.** These have no hooks, so
  they get an MCP server with two tools, `brain_memory_context` and
  `brain_memory_write`, and instructions that tell the agent to recall before it
  acts and to record what it learns.
- **Facts with a source, never overwritten.** Every fact records where it came
  from. A changed fact supersedes the old one, and `mycobrain-memory history`
  shows both and the reason.
- **Client boundaries, enforced in the database.** Houses keep clients apart, and
  only you create them. `mycobrain-memory binding add <name> --house <slug>`
  gives a contractor's agent one client and nothing else. Each tool gets its own
  credential, so you can see which tool wrote a fact and revoke one tool without
  touching the others.
- **No API keys.** The worker reads sessions with your own Claude or Codex
  subscription, through the `claude` or `codex` CLI you are already signed in to.
  Embeddings run locally with Ollama if you have it. Without Ollama, recall
  matches the words of your prompt, which works well for names, places and
  numbers.
- **Dream, off by default.** Turn it on and it proposes merges of duplicate
  facts, per-client dossiers and cross-client patterns. Nothing changes until you
  approve a proposal with `mycobrain-memory review approve`.

Check it at any time with `mycobrain-doctor --memory`. Walkthrough:
[docs/memory-quickstart.md](docs/memory-quickstart.md). Every command:
[docs/memory-cli.md](docs/memory-cli.md).

Before release we ran the documented commands from the packed npm tarball in a
fresh home directory, set up as a fictional landscape firm. A decision made in
the first session came back unprompted in the third. A change superseded the old
fact and kept its history. An agent scoped to one client found nothing from
another. With the database stopped, sessions still started and a write was
queued and delivered later. Uninstall put the config files back byte for byte.

## The document engine (optional)

The engine is the part of Myco Brain that came first: ingest documents, repos and
chat exports, search them, build a knowledge graph, and trace every answer to the
document it came from. It runs as a Docker stack, next to the memory layer or on
its own. Add it when you want answers from your documents, not only the facts
your agents record. Most of what follows is about the engine.

![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, 13 engine 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 (from your data export) and your AI knows you on day one.

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:
[Memory in two commands](#memory-for-your-agents-in-two-commands) ·
[Engine 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-