Myco Brain

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.

Memory for your agents in two commands

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 --house 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. Every command: 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.

• 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.

# 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.

Quick links: Memory in two commands · Engine quickstart · Teach your agent to use it well · The trust engine · Benchmark — run it yourself · Run every proof · Who it's for · Environment variables · Architecture · Roadmap · Cloud waitlist

Memory that gets more trustworthy (compounding confidence)

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

• 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.

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).

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

You pick the trust dial:

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

mycobrain review                 # list pending entities, relationships, types

mycobrain review approve # promote it into the graph mycobrain review reject # 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

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 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 rol