\n\n**Persistent, source-traceable memory for AI agents — self-hosted on your own Postgres, with no API keys required to run.**\n\n[](https://github.com/thegoodguysla/myco-brain/actions)\n[](https://www.npmjs.com/package/@mycobrain/mcp-server)\n[](./evals/longmemeval/README.md)\n[](./LICENSE)\n[](https://modelcontextprotocol.io)\n\n\n\n- **Source-traceable.** Every fact traces to the document it came from (`brain_why`) — no trust-me summaries.\n- **Trust that compounds.** Independent corroboration _raises_ a fact's confidence; a contradiction _supersedes_ it — kept and audited, never silently overwritten.\n- **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.\n- **Yours.** Apache-2.0, plain Postgres tables, 13 MCP tools. Works with Claude, Cursor, Windsurf, Continue, Zed.\n\n**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.\n\n_Built solo by a growth marketer — not a career engineer — directing AI coding agents over ~3 months. [How it was built ↓](#who-built-this)_\n\nThe usual fix for agent amnesia — letting an LLM maintain its own memory —\nfills it with duplicates, hallucinated summaries, and confident answers nobody\ncan trace. Myco Brain is built on the opposite contract:\n\n> **The LLM proposes. Deterministic rules decide what becomes a fact. You set\n> the bar** — from corroboration-gated auto-promotion (the default) to strict\n> human review of every fact (`BRAIN_REQUIRE_HUMAN_REVIEW=1`).\n\nClaude, Cursor, Windsurf, Continue, Zed, and custom agents all share one memory\nbacked by your own Postgres.\n\n⭐ If the trust model resonates, a star helps others find it.\n\n```bash\n# 1. Boot the stack (Postgres + MCP server + extraction worker)\ngit clone https://github.com/thegoodguysla/myco-brain.git && cd myco-brain\ndocker compose up -d\n\n# 2. Give your agent a memory — point it at any repo or folder\n# (no env needed: it finds the quickstart stack on localhost)\nnpx -y -p @mycobrain/mcp-server mycobrain-ingest github:your-org/your-repo\n\n# 3. Connect your client (one-liner below), then ask across sessions:\n# \"what did we decide about auth, and where is that documented?\"\n# → answered from your docs, with the source cited.\n```\n\n> [!TIP]\n> **Zero API keys, all the way down.** Full-text search, semantic search (local\n> embeddings), and the knowledge graph (local extraction) all run with no hosted\n> dependency. Add an Anthropic key only if you want the most accurate graph.\n\n**MCP-native by design — your agent knows _when_ to use memory, not just _how_.**\nMost MCP servers expose tools and hope the model calls them. Myco ships a usage\ncontract over MCP's `instructions` channel: the moment it connects, your agent\nknows to pull context before a task, save durable decisions, and cite sources\nwith `brain_why` — no per-project prompting. Tune the policy in one copy-paste\nblock: [Teach your agent to use it well](./docs/agent-setup.md).\n\nQuick links:\n[10-minute quickstart](#get-started-in-under-10-minutes) ·\n[Teach your agent to use it well](./docs/agent-setup.md) ·\n[The trust engine](#memory-that-gets-more-trustworthy-compounding-confidence) ·\n[Benchmark — run it yourself](#benchmark--run-it-yourself) ·\n[Run every proof](#every-claim-has-a-check) ·\n[Who it's for](#who-its-for) ·\n[Environment variables](#environment-variables) ·\n[Architecture](#architecture) ·\n[Roadmap](./ROADMAP.md) ·\n[Cloud waitlist](#cloud-waitlist)\n\n## Memory that gets more trustworthy (compounding confidence)\n\nMost agent memory **overwrites** facts silently. Myco Brain **compounds** them:\n\n\n\n- An independent source agreeing with a fact **raises** its confidence\n (damped noisy-OR — ten chunks of one document corroborate nothing; only\n distinct sources count).\n- A confident contradiction on a single-valued relationship (who you *work\n for*, where something *is located*) **supersedes** the old fact: it's\n closed and weakened — **kept, never deleted** — with the supersession\n recorded in an audited claims ledger.\n- Ask `brain_why` about any fact and you get its **distinct** source count (per\n relationship, not per mention), its confidence trend over time (\"0.8 → 0.86\"),\n and any superseded history.\n Contradictions stay visible. Your memory can't gaslight you.\n\n```text\nworks for → Halcyon Labs 0.55 [SUPERSEDED — kept, not deleted]\nworks for → Driftwood Analytics 0.90 [ACTIVE]\nclaims ledger: old fact superseded_by → new fact (audited)\n```\n\n*Proof: `npm run test:compounding` — the full lifecycle runs against a live\ndatabase in seconds, no LLM required.*\n\n## The schema evolves with your data (dynamic schema)\n\n- The extraction worker notices entity kinds and relationship types your catalog\n doesn't have yet and **proposes** them (`brain_stats`: *\"Brain proposed 3 new\n types from your data\"*).\n- **Promotion is yours by default** — or opt into auto-promotion for types\n corroborated across enough **distinct source documents**\n (`BRAIN_SCHEMA_AUTO_PROMOTE=1`), counted per document, not per mention, so two\n documents passed back and forth can't manufacture consensus. One chatty\n document can never promote anything.\n- A promoted type stays **scoped to the workspace that earned it** — one client's\n vocabulary never leaks into another's catalog (see\n [per-client isolation](#one-isolated-workspace-per-client--built-for-agencies)).\n\n*Proofs: `npm run test:dynamic-schema`, `npm run test:schema-promotion`.*\n\n**You pick the trust dial:**\n\n| Mode | Behavior |\n|---|---|\n| Default | Confident facts auto-promote; novel types wait for review |\n| `BRAIN_REQUIRE_HUMAN_REVIEW=1` | **Strict curation** — nothing the LLM proposes touches the canonical graph without a human decision |\n| `BRAIN_SCHEMA_AUTO_PROMOTE=1` | Corroborated new types promote themselves, audited |\n\nWhen something is waiting on you — novel types in default mode, or everything\nin strict mode — review it from the command line:\n\n```bash\nmycobrain review # list pending entities, relationships, types\nmycobrain review approve # promote it into the graph\nmycobrain review reject # reject it (kept and audited, never deleted)\n```\n\n*Proof: `npm run test:review` — approving actually lands the entity / edge /\ntype in the canonical graph; rejecting never does.*\n\n## Private memories, shared knowledge\n\nMulti-agent teams get real isolation: documents marked `private` are readable\n**only by the agent that created them** — enforced in every read tool, on top\nof workspace row-level security. Workspace memory stays shared. *Proof:\n`npm run test:sharing` (a two-agent visibility matrix).* Like workspace\nisolation, it binds only under the least-privilege `brain_app` role\n([security note](#one-isolated-workspace-per-client--built-for-agencies)).\n\n## One isolated workspace per client — built for agencies\n\nPut each client in their own workspace, share one agency-wide playbook, and\nthe guarantee you sell is **Postgres row-level security** — a session scoped\nto Client A cannot return Client B's rows. The\n[agency starter kit](./examples/agency/) provisions it (one command) and ships\nthe least-privilege DB role that makes the isolation actually bind. *Proof:\n`npm run test:agency` — Client A sees zero of Client B's facts.*\n\n> [!IMPORTANT]\n> **Isolation binds only under the least-privilege role.** RLS does not constrain\n> a Postgres **superuser**, and the zero-config quickstart's default `brain` role\n> *is* a superuser (fine for a single-workspace self-host — there's nothing to\n> isolate). Before you put more than one client in one database, run the app as\n> the `NOSUPERUSER` `brain_app` role the agency kit ships; `mycobrain-doctor`\n> flags a superuser connection. Multi-tenant isolation is a guarantee of\n> `brain_app`, not of the default quickstart role.\n\n\nAdvanced — multi-tenant gateways: who is the caller? (BRAIN_TRUST_REQUEST_IDENTITY)\n\n \n\nRLS decides *which rows a tenant can read*; this setting decides *which tenant a\nrequest is* — the step before RLS. On the **stdio** server, identity is taken\n**only from the server's environment** by default: a `workspace_id`, `agent_id`,\nor `api_key` supplied in tool-call arguments is **ignored**, so even a\nprompt-injected agent can't pass `workspace_id: \"\"` to reach\nanother workspace. (For `brain_` keys, identity comes from the key string and\nnothing else.)\n\nSet `BRAIN_TRUST_REQUEST_IDENTITY=1` **only** when you front the server with a\nreal multi-tenant gateway that authenticates each request and maps it to a\ntenant itself — then per-request identity is honored (and a service-role JWT\nmust **equal** `BRAIN_SERVICE_ROLE_KEY`, not merely look like one). **Single-tenant\nself-hosts need none of this** — their identity is already environment-derived.\n\n\n\n## Query over HTTP (read-only)\n\nNot everything speaks MCP. For a web app, an automation, or a partner backend,\n`mycobrain-rest` puts a small read-only API in front of the brain — exactly two\ntools, `search` and `why`, plus health:\n\n```bash\nmycobrain-rest # → http://127.0.0.1:8787\n\ncurl -s localhost:8787/search \\\n -H \"Authorization: Bearer brain___\" \\\n -d '{\"query\":\"what did we decide about pricing?\",\"limit\":5}'\n```\n\n- **Scoping:** the key scopes every query to its workspace (same RLS as MCP), and\n there are **no write routes**. Like MCP, this binds only under the least-privilege\n `brain_app` role ([security note](#one-isolated-workspace-per-client--built-for-agencies)) —\n never expose REST as the default `brain` superuser (`mycobrain-doctor` flags it).\n- **Key verification:** installs migrated to `…_agent_api_key_verification.sql`\n verify each key's `` against `agent_api_keys` once a secret is registered\n (register/rotate via `brain_set_agent_api_key_secret(...)`). Until then the key\n acts as a bearer token; set `BRAIN_REQUIRE_API_KEY_SECRET=1` to require a\n registered secret before exposing REST.\n- **Binding:** loopback by default — set `BRAIN_REST_HOST=0.0.0.0` behind your own\n TLS/proxy only when you mean to expose it, and treat the key like a password.\n\n*Proof: `npm run test:rest`.*\n\n## Five Verified Demos\n\n### 1. Cross-session recall\n\nSave a fact in one conversation:\n\n```text\nSave a memory: the board meeting is every Wednesday at 9 AM Pacific.\n```\n\nStart a fresh conversation and ask:\n\n```text\nWhat time is the board meeting?\n```\n\nExpected result: the new session retrieves the stored fact instead of relying on chat history.\n\n### 2. Cross-agent shared memory\n\nWrite from one client:\n\n```text\nSave a memory: Acme's renewal call is on October 15 with Jordan.\n```\n\nRead from another client:\n\n```text\nWhat is Acme's renewal date?\n```\n\nExpected result: both clients read the same shared memory because the source of truth is Postgres, not a single chat thread.\n\n### 3. Provenance for answers\n\nAsk `brain_why` about any fact and get the source chain — not a trust-me summary.\nReal output for an entity built from the demo corpus:\n\n```json\n{\n \"subject\": { \"kind\": \"entity\", \"name\": \"Mara Quinn\" },\n \"evidence\": {\n \"mention_count\": 4,\n \"source_document_count\": 4,\n \"summary\": \"Supported by 4 mentions across 4 source documents.\"\n },\n \"source_proposals\": [\n { \"extracted_by\": \"ollama:llama3.2:3b\", \"confidence\": 1, \"state\": \"auto_promoted\",\n \"source_hyobject_id\": \"8e31414c-…\" }\n ]\n}\n```\n\nEvery accepted fact traces to the document(s) it came from and how it was extracted.\n\n### 4. Document ingestion with sources\n\nIngest a file or URL:\n\n```text\nIngest ./docs/customer-handbook.pdf and summarize the onboarding checklist with sources.\n```\n\nExpected result: the document is chunked, indexed, and cited back through retrieval.\n\n### 5. Graph relationships\n\nAsk:\n\n```text\nShow related entities for Acme and explain how they connect.\n```\n\nExpected result: relationship queries surface connected people, documents, and entities — and the **entity-to-entity edges** the extraction worker builds (e.g. *Mara Quinn —manages→ Northwind Coffee*) — instead of flat vector matches. Build this graph [locally with Ollama](#build-the-knowledge-graph--locally-no-api-keys), no API key required.\n\n> All demos are **code, not screen recordings** — `demos/` re-renders them\n> deterministically against a fresh stack (`npm run demo:render -- all`).\n\n## How Myco compares\n\nDifferent tools make different tradeoffs; this compares architectural\n**approaches**, not benchmarked head-to-heads — when retrieval recall is high\nthe answer model becomes the bottleneck, so cross-system score comparisons\nmislead (see [the benchmark section](#benchmark--run-it-yourself)).\n\n| | Typical LLM-maintained memory | Framework memory (e.g. LangChain) | Myco Brain |\n|---|---|---|---|\n| Reproducible benchmark | Self-reported | — | **Harness ships in-repo** — reproduce the number yourself |\n| Fact extraction | LLM-based | LLM-based | Deterministic write path; LLM output enters only via gated proposal queues |\n| Contradicting facts | Coexist as independent records | Possible | **Superseded, never overwritten** — audited claims ledger |\n| Fact confidence | Static | — | **Compounds with independent evidence**, falls on contradiction |\n| Hallucinated facts | Possible | Possible | Constrained out of the write path |\n| Provenance | Partial | Partial | First-class via `brain_why` (source + audit trail + confidence trend) |\n| Shared memory | Depends on app wiring | Depends on app wiring | Native Postgres source of truth, multi-agent with per-object privacy |\n| Data portability | Vendor / framework shaped | Framework shaped | Plain Postgres tables |\n\n## Get Started In Under 10 Minutes\n\nVerified local path: Docker Compose from a fresh clone.\n\n```bash\ngit clone https://github.com/thegoodguysla/myco-brain.git\ncd myco-brain\ndocker compose up -d\n```\n\nWhat starts:\n\n- Postgres 16 + pgvector\n- MCP server\n- Extraction worker\n\nNo API keys required to boot — here's what each capability needs:\n\n| Capability | Out of the box? | To enable |\n|---|---|---|\n| Full-text (BM25) search | ✅ immediately | nothing |\n| Semantic search | needs embeddings | `BRAIN_EMBED_PROVIDER=ollama` (local, keyless) |\n| Knowledge graph | needs an extractor | [Ollama locally](#build-the-knowledge-graph--locally-no-api-keys) (keyless) or `BRAIN_ANTHROPIC_API_KEY` (most accurate) |\n\nConfirm it's healthy in one command. `mycobrain-doctor` doesn't just check that\nenv vars are set — for the local Ollama path it **live-verifies** the setup (pings\nOllama, confirms the embed/extraction models are pulled, and runs a real embed +\ngeneration), then checks the extraction backlog and review queue. It exits\nnon-zero only on a real failure (a red line), so green means it works:\n\n```bash\nnpx -y -p @mycobrain/mcp-server mycobrain-doctor\n```\n\nAdd `--fix` to have it offer to pull any missing Ollama models for you:\n\n```bash\nnpx -y -p @mycobrain/mcp-server mycobrain-doctor --fix\n```\n\n### Connect your client\n\n**Recommended — guided setup.** One command walks you through connecting an\nagent, with consent at every step:\n\n```bash\nnpx -y -p @mycobrain/mcp-server mycobrain-setup\n```\n\nIt runs pre-flight checks (each with an offered fix), verifies pgvector and a\nreal write to your database, wires up your MCP client (Claude Code, Claude\nDesktop, Cursor, Codex, Windsurf), and offers a one-tap import of your ChatGPT\nor Claude data export if the zip is already in `~/Downloads`. Each connected\nclient gets its own agent identity, so later recalls show which tool a memory\ncame from. Prefer to drive it yourself? The manual paths are below.\n\n**Claude Code** — by hand (uses the quickstart stack's seeded, public localdev\ncredentials):\n\n```bash\nclaude mcp add myco-brain \\\n --env DATABASE_URL=postgresql://brain:brain@localhost:5432/brain \\\n --env BRAIN_API_KEY=brain_00000000-0000-0000-0000-000000000001_00000000-0000-0000-0000-0000000000a1_localdev \\\n -- npx -y @mycobrain/mcp-server\n```\n\nRestart Claude Code and the `brain_*` tools are live — the server hands every\nconnected agent its usage contract automatically (when to recall, save, and\ncite), so it works well out of the box.\n\n**Claude Desktop** — add this to\n`~/Library/Application Support/Claude/claude_desktop_config.json`\n(**Cursor** and **Windsurf** take the same `mcpServers` block in\n`.cursor/mcp.json` / their MCP settings):\n\n```json\n{\n \"mcpServers\": {\n \"myco-brain\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mycobrain/mcp-server\"],\n \"env\": {\n \"DATABASE_URL\": \"postgresql://brain:brain@localhost:5432/brain\",\n \"BRAIN_WORKSPACE_ID\": \"00000000-0000-0000-0000-000000000001\",\n \"BRAIN_API_KEY\": \"brain_00000000-0000-0000-0000-000000000001_00000000-0000-0000-0000-0000000000a1_localdev\"\n }\n }\n }\n}\n```\n\n> **Note:** `BRAIN_WORKSPACE_ID` is derived from your `brain_` API key, so it is\n> optional — the Claude Code one-liner above omits it and works the same.\n\nThen test the happy path:\n\n```text\nSave a memory: the launch checklist lives in the ops folder.\n```\n\nOpen a new session and ask:\n\n```text\nWhere does the launch checklist live?\n```\n\nFull setup guide: [docs/quickstart.md](./docs/quickstart.md)\n\n### First run — the fastest path to *your* magic moment\n\nMyco ships **empty**. The \"whoa\" lands hardest on your *own* data, so the\nrecommended first step is to bring your history in:\n\n```bash\n# Guided getting-started — leads with importing your own history\nnpx -y -p @mycobrain/mcp-server mycobrain-onboard\n```\n\n```bash\n# Import your ChatGPT or Claude export (~30s), then ask your agent about your past\nmycobrain-ingest --from chatgpt-export ~/Downloads/.zip\nmycobrain-ingest --from claude-export ~/Downloads/.zip\n# → \"what did I decide about ?\" answered from your own conversations.\n```\n\nPrefer to skip it? Just start using it — Brain remembers as you work. Or take a\n**60-second live tour** on sample data that cleans up after itself (your\nworkspace is left untouched):\n\n```bash\nmycobrain-onboard --tour\n```\n\n### See it work with the demo corpus (optional sandbox)\n\nWant a richer guided example? Load the included demo corpus — a small set of\ninterconnected documents for a fictional agency and its client:\n\n```bash\nnpx -y -p @mycobrain/mcp-server mycobrain-ingest ./examples/demo-corpus\n```\n\nThen ask any connected agent:\n\n- *\"When does Northwind's rebrand launch, and who owns the account?\"*\n- *\"What pricing model did we choose for Northwind, and why?\"*\n- *\"Show me the source for that.\"* — provenance via `brain_why`\n- *\"Show my Myco memory stats.\"* — health snapshot via `brain_stats`\n\nEvery answer traces back to the document it came from. No API key required.\n\n**The finale:** the corpus contains a deliberate contradiction — one document\nsays Devin Osei works for Lumen, a later one says he left for Harbor & Co.\nWith the [keyless local graph](#build-the-knowledge-graph--locally-no-api-keys)\nrunning, ask:\n\n- *\"Who does Devin Osei work for? What changed, and how do you know?\"*\n\nThe old fact comes back **superseded — kept, not deleted** — with both source\ndocuments cited. That's the trust engine working on your data, not a demo\nscript.\n\nDone exploring? Clear *only* the bundled sample data (your own imports and\nmemories are never touched) with:\n\n```bash\nmycobrain-onboard --reset-demo\n```\n\n## Bulk-ingest a folder or repo\n\nPoint Brain at a directory or a GitHub repo and it indexes every text file —\nsearchable across sessions, with each answer traceable to its source file.\n\n```bash\nnpx -y -p @mycobrain/mcp-server mycobrain-ingest ./docs # a local folder\nnpx -y -p @mycobrain/mcp-server mycobrain-ingest github:owner/repo # a GitHub repo\n```\n\nNo env needed against the quickstart stack — the CLI defaults to it. For your\nown Postgres or workspace, set the same env vars the MCP server uses\n(`DATABASE_URL`, `BRAIN_WORKSPACE_ID`, `BRAIN_API_KEY`).\n\nThen ask any connected agent: *\"search my ingested files for the auth flow\"* or\n*\"show my Myco memory stats\"*. Set `GITHUB_TOKEN` for private repos.\n\n## Build the knowledge graph — locally, no API keys\n\nWhat separates Myco from a vector store is the **graph**. The extraction worker\nreads your ingested documents and:\n\n- pulls out the **entities** — people, companies, projects, places;\n- **collapses duplicates** so \"Priya\" and \"Priya Raman\" become one node;\n- connects them with **directed relationships** — *Mara Quinn —works for→\n Northwind Coffee*, never the reverse (the shipped prompt is direction-aware,\n and endpoints the model forgets to list are recovered automatically);\n- and **proposes new types** it observes, so the schema grows with your domain.\n\nYou choose which model does the extraction. **Nothing leaves your machine with\nOllama; Anthropic produces the most accurate graph.**\n\nTwo distinct, often-conflated quality measures on the 14-edge gold fixture\n(*proof: `npm run test:direction`*):\n\n| Metric | What it measures | Score |\n|---|---|---|\n| **Directed accuracy** | edges point the right way | **86%** (12/14, `llama3.2:3b`) |\n| **Edge survival** | endpoints recovered, not dropped | **~80%** (11–12/14, gated ≥75%) |\n\n### Option A — Local & free (Ollama, no API key)\n\n```bash\n# Install Ollama (https://ollama.com/download), then pull a model:\nollama pull llama3.2:3b\n\n# Point the worker at it and restart:\necho \"BRAIN_OLLAMA_BASE_URL=http://host.docker.internal:11434\" >> .env\ndocker compose up -d\n```\n\n### Option B — Most accurate (Anthropic, bring your key)\n\n```bash\necho \"BRAIN_ANTHROPIC_API_KEY=sk-ant-...\" >> .env\ndocker compose up -d\n```\n\nIf both are configured, Anthropic is used automatically (it's more accurate);\nforce a choice with `BRAIN_EXTRACTION_PROVIDER=ollama|anthropic`.\n\n### Try it\n\nIngest a few documents, give the worker a moment, then ask a connected agent:\n\n- *\"What entities are in my Northwind documents?\"* — `brain_neighbors`\n- *\"How does Mara Quinn connect to Northwind?\"* — entity-to-entity relationships\n- *\"Show my Myco memory stats.\"* — watch the graph grow (`brain_stats`)\n\nEither way, the canonical graph lives in your Postgres — the model only\n*proposes*; the database decides what becomes a durable fact.\n\n## Benchmark — run it yourself\n\nThe point here is **reproducibility, not a single score** — the\n[LongMemEval](https://github.com/xiaowu0162/LongMemEval) harness ships in this\nrepo, so you run the numbers yourself; we don't assert them.\n\n| Metric | Subset (500q) | Config | Score |\n|---|---|---|---|\n| End-to-end QA | `oracle` | reader gpt-4o-mini · judge gpt-4o | **73.6%** |\n| End-to-end QA | `oracle` | strong reader (gpt-4o) | 71.8% |\n| Evidence recall@5 (`Ev@5`) | `longmemeval_s` | hybrid (vector + BM25) | **89.2%** |\n| Evidence recall@5 (`Ev@5`) | `longmemeval_s` | keyless recency reranker | **91.6%** |\n| Evidence recall@10 | `longmemeval_s` | hybrid → recency | 90.2% → 93.2% |\n\n**End-to-end QA** uses the `oracle` subset, which hands the reader only the gold\nevidence sessions — so it isolates *reasoning*, not retrieval (that's `Ev@5`,\nbelow). The strong-reader config scores *lower* (gpt-4o, 71.8%): with the evidence\nalready in context the memory layer is saturated, so the reader isn't the binding\nconstraint — exactly why single-headline comparisons across systems mislead.\nNumbers others quote in the ~90% range are typically a different subset, reader,\nand judge; we're not claiming a head-to-head win, just handing you the harness to\nscore any system on the same footing.\n\n```bash\ncd evals/longmemeval && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt && cd ../..\nOPENAI_API_KEY=sk-... DATABASE_URL=postgresql://brain:brain@localhost:5432/brain \\\n evals/longmemeval/.venv/bin/python3 -m evals.longmemeval.run \\\n --examples 500 --subset longmemeval_oracle --judge-model gpt-4o\n```\n\n**Retrieval quality** (`Ev@5` in the table) is the real retrieval metric — the\n`oracle` subset above doesn't test it — measured on the full `longmemeval_s`\nsubset *with distractors*. The **recency reranker** (`brain_search(reranker:\n'recency')`) is deterministic: no API key, no network call. Hybrid retrieval needs\nan embedding provider (keyless via local Ollama, or OpenAI); stock BM25-only\nsearch scores lower. Reproduce (embeddings only, no judge):\n`python -m evals.longmemeval.run --subset longmemeval_s -n 500 --no-qa`.\n\nMethodology, both configs, per-category breakdown (including the categories\nthat are hard for us — reported, not hidden), and cheaper sample commands:\n[evals/longmemeval/README.md](evals/longmemeval/README.md).\n\n## Every claim has a check\n\nNothing on this page asks for your trust — each capability names the runnable\nproof that gates it in development. (Run the `npm run` and `node test/` checks\nfrom `mcp-server/` after `npm install`; `node examples/` and `evals/` paths are\nrelative to the repo root.)\n\n| Claim | Check |\n|---|---|\n| Quickstart works end-to-end | `node test/quickstart-e2e.mjs` (also runs in CI against the real Docker stack) |\n| Duplicates can't happen; provenance is total | `node examples/benchmark/run.mjs` |\n| Keyless semantic search finds meaning, not words | `npm run test:local-embeddings` |\n| Relationships are direction-aware; edges survive | `npm run test:direction` |\n| Confidence rises with evidence, contradiction supersedes | `npm run test:compounding` |\n| New types are proposed (and auto-promote only when corroborated + opted-in) | `npm run test:dynamic-schema` · `npm run test:schema-promotion` |\n| Strict curation mode blocks all auto-promotion | `npm run test:strict-mode` |\n| Private documents are private | `npm run test:sharing` |\n| All 13 tools fit in your context (~2.5K tokens, not bloat) | `npm run audit:tokens` |\n| Agency: Client A can't read Client B (workspace RLS) | `npm run test:agency` |\n| Reviewing a proposal actually promotes/rejects it | `npm run test:review` |\n| Read-only REST API: auth, read-only, DoS-capped | `npm run test:rest` |\n| The benchmark number | `evals/longmemeval/` (full harness in-repo) |\n\n## Who it's for\n\nMyco is the memory layer for any team whose AI agents need to remember, with\nreceipts. Each page below reframes it for your audience and walks the same use\ncases across industries (FinTech, Healthcare, Legal, Accounting, Insurance,\nSaaS, customer support, e-commerce).\n\n- **[Developers](https://mycobrain.dev/for/builders)** building agents for production: one MCP server, a deterministic write path, and provenance you own.\n- **[Vibecoders](https://mycobrain.dev/for/vibecoders)** shipping fast: persistent memory in one line, keyless and free, with no infra to build.\n- **[Teams](https://mycobrain.dev/for/teams)** putting AI in a product: customer memory, isolated per tenant, on Postgres you own.\n- **[Agencies](https://mycobrain.dev/for/agencies)**: every client in an isolated, auditable workspace.\n\n## Architecture\n\n
\n \n
\n\nThe design is simple on purpose: **the database is authoritative, the write\npath is programmatic, and LLMs assist without becoming the memory store.**\n\n## Tool Surface\n\nMyco Brain exposes 13 MCP tools:\n\n- `brain_context_pack`\n- `brain_search`\n- `brain_why`\n- `brain_neighbors`\n- `brain_ingest`\n- `brain_propose_fact`\n- `brain_annotate`\n- `brain_save_memory`\n- `brain_recall_memory`\n- `brain_get_related`\n- `brain_stats`\n- `brain_set_mode`\n- `brain_self_check`\n\nFull inputs, outputs, and examples for each tool: **[docs/api-reference.md](./docs/api-reference.md)**.\n\n## Environment variables\n\nThe Docker quickstart needs **none** of these — it ships with seeded local\ncredentials and BM25 search works immediately. This is the reference for your\nown deployment. Full annotated list with tuning thresholds:\n[`.env.example`](./.env.example). Not sure what's active? Run `mycobrain-doctor`.\n\n**Required**\n\n| Variable | Default | What it does |\n|---|---|---|\n| `DATABASE_URL` | — | Postgres connection string. The only hard requirement. |\n| `BRAIN_API_KEY` | seeded | `brain___` key; the quickstart ships a localdev key. |\n| `BRAIN_WORKSPACE_ID` | from key | Derived from `BRAIN_API_KEY`; set explicitly only for service-role auth. |\n\n**Semantic search** *(optional — without it, BM25 full-text still works)*\n\n| Variable | Default | What it does |\n|---|---|---|\n| `BRAIN_EMBED_PROVIDER` | auto | `ollama` or `openai`; auto-selects by which credential is set. |\n| `BRAIN_OLLAMA_EMBED_MODEL` | `nomic-embed-text` | Local embedding model (no key, nothing leaves your machine). |\n| `BRAIN_OPENAI_API_KEY` | — | Use OpenAI embeddings instead of local. |\n\n**Knowledge graph** *(optional)*\n\n| Variable | Default | What it does |\n|---|---|---|\n| `BRAIN_OLLAMA_BASE_URL` | — | Local extraction/embeddings endpoint (e.g. `http://localhost:11434`). |\n| `BRAIN_OLLAMA_MODEL` | `llama3.2:3b` | Local extraction model. |\n| `BRAIN_ANTHROPIC_API_KEY` | — | Most accurate graph; used automatically if set. |\n| `BRAIN_EXTRACTION_PROVIDER` | auto | Force `ollama` or `anthropic`. |\n\n**Trust dial** *(governance)*\n\n| Variable | Default | What it does |\n|---|---|---|\n| `BRAIN_REQUIRE_HUMAN_REVIEW` | `0` | Strict curation — nothing the LLM proposes enters the graph without a human decision. |\n| `BRAIN_SCHEMA_AUTO_PROMOTE` | `0` | Let corroborated new types promote themselves, audited and workspace-scoped. |\n\n**Serving**\n\n| Variable | Default | What it does |\n|---|---|---|\n| `BRAIN_REST_HOST` | `127.0.0.1` | Bind host for `mycobrain-rest`. Use `0.0.0.0` only behind your own TLS/proxy. |\n| `BRAIN_REST_PORT` | `8787` | Read-only REST port. |\n| `BRAIN_HEALTH_PORT` | `8080` | Health-check port. |\n\n**Identity & security**\n\n| Variable | Default | What it does |\n|---|---|---|\n| `BRAIN_REQUIRE_API_KEY_SECRET` | `0` | Require a registered `` for every agent key before auth succeeds. |\n| `BRAIN_TRUST_REQUEST_IDENTITY` | `0` | **Stdio, multi-tenant gateways only.** Off: identity comes solely from env, so a caller-supplied `workspace_id`/`api_key` is ignored (prompt-injection-resistant). Set `1` only behind a gateway that authenticates each request. [Details ↑](#multi-tenant-gateways-who-is-the-caller-brain_trust_request_identity) |\n| `BRAIN_AGENT_ID` | from key | Agent identity for service-role auth; derived from `BRAIN_API_KEY` otherwise. |\n| `BRAIN_SERVICE_ROLE_KEY` | — | Supabase service-role JWT for trusted service callers (alternative to a `brain_` key). |\n\n> Tuning thresholds (`BRAIN_SCHEMA_PROMOTE_MIN_SEEN`, `BRAIN_EXTRACTION_LEASE_MS`, `BRAIN_FUNCTIONAL_PREDICATES`, …) live in [`.env.example`](./.env.example).\n\n## Repository Layout\n\n```text\nmyco-brain/\n├── mcp-server/ # TypeScript MCP server + bulk-ingest CLI\n├── supabase/migrations/ # versioned SQL migrations\n├── demos/ # demos-as-code (VHS + ffmpeg + narration pipeline)\n├── docs/quickstart.md # setup guide\n├── evals/\n│ └── longmemeval/ # LongMemEval benchmark harness (run it yourself)\n├── examples/\n│ ├── demo-corpus/ # sample interconnected docs to ingest\n│ └── benchmark/ # reproducible dedup + provenance benchmark\n├── docker-compose.yml # local quickstart\n├── ROADMAP.md # where this is headed\n└── LICENSE # Apache-2.0\n```\n\n## Import your ChatGPT / Claude history\n\nMonths of assistant conversations become provenance-tracked, deduplicated,\nsearchable memory — one document per conversation:\n\n```bash\n# Official OpenAI data export (zip, extracted folder, or conversations.json)\nmycobrain-ingest --from chatgpt-export ./chatgpt-export.zip\n\n# claude.ai data export\nmycobrain-ingest --from claude-export ./claude-export.zip\n```\n\n- **Re-importing never duplicates** — each conversation is one content-hash-keyed\n document, so a re-run is a no-op. Continue a conversation and re-export, and the\n longer transcript imports as a new version alongside the old.\n- **Branched ChatGPT threads import the ACTIVE branch** — the transcript you\n actually kept, not rejected regenerations.\n- **Full provenance** — `brain_why` traces every imported fact back to its export file.\n\n*Proof: `npm run test:export-import`.*\n\n**Hands-free — watch your Downloads.** Request your export, then let Myco import\nit the moment it lands, with no path to copy and nothing leaving your machine:\n\n```bash\n# Poll ~/Downloads and auto-import a ChatGPT/Claude export the second it arrives (Ctrl-C to stop)\nmycobrain-ingest --watch-downloads\n\n# Already downloaded it? Import whatever export is there, then exit\nmycobrain-ingest --watch-downloads --once\n```\n\nOpt-in and deduplicated like any other import; point it at a different folder\nwith `BRAIN_WATCH_DIR` (needs `unzip` on your PATH).\n\n## Cloud Waitlist\n\nSelf-hosting is the default. If you want managed hosting instead, join the waitlist:\n\n**[mycobrain.dev](https://mycobrain.dev)**\n\nThat page is the canonical waitlist entrypoint. This README intentionally does not embed a form.\n\n## OSS Files\n\n- [CONTRIBUTING.md](./CONTRIBUTING.md)\n- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)\n- [SECURITY.md](./SECURITY.md)\n- [NOTICE](./NOTICE)\n- [LICENSE](./LICENSE)\n\n## Resources\n\n- [Quickstart](./docs/quickstart.md)\n- [npm package](https://www.npmjs.com/package/@mycobrain/mcp-server)\n- [Changelog](./CHANGELOG.md)\n- [Audience + industry use cases](https://mycobrain.dev/for/builders)\n- [Issue tracker](https://github.com/thegoodguysla/myco-brain/issues)\n- [Cloud waitlist](https://mycobrain.dev)\n\n## Who built this\n\nMyco Brain was built by **Nick Taylor** — a growth marketer, not a career engineer — directing a team of AI coding agents. Roughly three months and about $6k in model spend, built with AI-assisted engineering. The point isn't the price tag; it's that a clear product vision plus modern agent tooling can now ship production-grade infrastructure — and this repo is the result: every claim on this page names a runnable check (see [Every claim has a check](#every-claim-has-a-check)), so you can judge it yourself rather than take the origin story on faith.\n\n**Like this?** A ⭐ helps others find it, and *Watch → Releases* (top of the page) will ping you when new capabilities ship — see the [roadmap](./ROADMAP.md) for what's next.\n\n**Want this for your team?** If your company wants someone who can build agent systems, automation, and growth engineering like this, that's what **The Good Guys** does — email [nick@thegoodguys.la](mailto:nick@thegoodguys.la) or [book a call](https://calendar.app.google/B6pSrRvv3FWX9C4u8).\n",
"bytes": 35812,
"sha": "0b20ab21c7aec0e1351d62341b12cac011d9960af946198d7efb71b4105fd848",
"repo_slug": "thegoodguysla/myco-brain",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_thegoodguysla_myco_brain_0164c1a1/readme"
}
![\"Myco](\"./docs/assets/myco-logo-dark.png\"){kind=logo}
\n ![\"Myco](\"./docs/architecture.svg\")
\n