MemoryBrain

Open Brain — A Knowledge Management Framework

Open Brain is an opinionated framework for building and maintaining personal knowledge vaults that stay useful as they scale. It addresses the core problem most PKM systems ignore: notes don't just need to be captured — they need to be found, connected, kept alive, tested, and turned into output.

[MemoryBrain](https://memorybrain.ai) is built on Open Brain. Open Brain defines how a brain is built; MemoryBrain is where it lives inside your AIs (ChatGPT and Claude, through a remote MCP connector). The skills are listed at memorybrain.ai/openbrain/skills.

Most knowledge management systems work well at 50 notes. At 500, search gets noisy. At 2,000+, the vault becomes a graveyard of ideas you know you wrote down but can't surface when you need them. And at every scale, without active recall and deliberate output, the knowledge never becomes skill.

Open Brain addresses this with a structured approach across eight modules — from first capture through to written thinking and system automation. The repo has two parts:

• `docs/` — 46 problem/solution docs that explain the framework. They are tool-agnostic.
• `skills/` — 23 Claude Code skills that implement it on a Markdown vault (see Skills).
• `engines/` — the Python scripts those skills call for the deterministic work: graph, retrieval log, health checks, lint, course build.

Some parts of the framework are practices you run by hand rather than features a skill runs for you — publishing, measuring how much your vault improves an output, and mining your own sessions for automation. The docs say so where it applies.

---

Try it in two minutes

example-vault/ is a small vault: 33 notes built from two invented books. Everything in it is fictional. It contains six deliberately seeded defects, so you can see what the engines catch and what they miss. You don't need a vault of your own or Claude Code: only Python 3.9+.

git clone https://github.com/Memory-brain/open-brain.git

cd open-brain pip install pyyaml # optional; without it one informational check reports 0 python3 engines/health-engine/health_check.py self-test bash example-vault/run-demo.sh

run-demo.sh copies the vault to a temporary directory, runs five engines there and deletes the copy afterwards, so nothing is written into the repo. The five engines are autolink (typed graph), the health check, the enrich scan, a one-hop graph retrieval and the eval. The excerpt below is real output from 2026-10-14, trimmed: … marks a cut, and checks that reported 0 are left out of the summary.

== 1. Autolink: index the vault and build the typed graph ==

✅ Indexed 33 notes → entities.json ✅ Wrote 130 edges → graph.jsonl … 🔖 Index edges (frontmatter): 97 🎯 Signal/noise ratio: 54.5% (18/33 non-trivial claim edges)

== 2. Health check (deterministic checks) == "summary": { "Orphan Notes": 1, "Unprocessed Inbox (>30d)": 1, "Contradiction Scan": 1, "skill_sequence Adoption & Signal": 3, "PN Provenance (resolved sources:)": 1, "Description as Claim, Not Label": 2, … -- details of the checks that fired -- [1] Orphan Notes: count=1 items: ["Small teams beat large teams on ambiguous work"] [5] Unprocessed Inbox (>30d): count=1 items: [{"note": "The Quiet Standup", "days": 63, "rating": 3}] [12] Contradiction Scan: count=1 items: [{"a": "A new routine sticks when it is small enough to run on a bad day", "b": "Judge a practice by its weekly review, not by its daily streak", "type": "contradice", …}] [16] Search Term Crowding: count=0 yellow_top: [{"term": "Habit Formation", "tag_count": 12, "tier": "flat", "threshold": 20, …}] [36] PN Provenance (resolved sources:): count=1 single_author_items: [{"pn": "Small teams beat large teams on ambiguous work", "author": "dov hartigan", "sources": 2}] [46] Description as Claim, Not Label: count=2 topic_not_claim: {"total": 1, "sample": ["Literature Notes/TF - A fixed weekly rhythm makes a small team pred"]}

== 3. Enrich scan (notes under 3 specific, resolvable search terms) == "under_threshold": [ { "note": "SL - A broken streak predicts dropout more than a missed day", "specific_resolvable": 2, … == 4. Retrieval: one-hop graph expansion from a seed note == Score Edge Type Dir Seed Neighbor 5.0 contradice → Judge a practice by its weekly review, n A new routine sticks when it is small enough to ru 1.0 refuerza → Judge a practice by its weekly review, n Team rituals need an owner and a cue, not just a c 1.0 refuerza ← Judge a practice by its weekly review, n Restarting an evening reading habit after a broken

== 5. Eval (L1 metrics across six dimensions) == "integrity": { "frontmatter_compliance_pct": 100.0, … "broken_links": 0, "orphan_pns": 1, … "graph": { "total_edges": 130, "total_entities": 33, "edges_per_entity": 3.94, "signal_noise_ratio_pct": 54.5, … "pipeline": { "inbox_total": 3, "inbox_stale_30d": 1,

Of the six seeded defects, four are caught and one is caught only in part:

• Caught: the stale Inbox item, the orphan Permanent Note, the topic-style description and the Literature Note with only two search terms.
• Caught in part: the crowded term Habit Formation. It shows up in the yellow band (12 notes), but the check's count stays 0 because a flat term only counts as red above 20 notes.
• Missed: a broken wikilink inside a Literature Note. Broken-link checks only scan Permanent Notes.

example-vault/README.md lists each defect, where it is and which check is expected to catch it. Edge types in the graph keep their original Spanish identifiers: contradice = contradicts, refuerza = reinforces, extiende = extends.

---

The Eight Modules

Module 1: Knowledge Enrichment

The foundation. Addresses the three failures that compound as a vault grows: notes becoming unfindable, search terms losing discriminative power, and knowledge connections carrying no semantic meaning.

Problems:

• Retrieval Decay — Notes become progressively harder to find as your vocabulary evolves
• Term Saturation — When a search term accumulates so many notes it loses discriminative power
• Knowledge Graph Signal vs. Noise — Why generic "mentions" links make the graph useless

Solution:

• The Enrichment Pattern — Evidence-driven search term repair, term splitting, and typed connections between Permanent Notes

---

Module 2: Knowledge Extraction

How raw sources — books, articles, PDFs, web content — become atomic, structured notes. The quality of extraction determines the quality of everything downstream. Includes both passive extraction (from sources you read) and active research (filling gaps you identify).

Problems:

• Source Overwhelm — The unprocessed inbox: capture without extraction is organized procrastination
• Atomic Note Decomposition — Getting the granularity right when converting a book to notes
• The Re-reading Trap — When your notes fail as references and you keep returning to the original
• Reactive Knowledge Accumulation — When the vault only reflects what you happened to read, not what you need to know
• The Seven Extraction Layers — What a source contains, why slotting notes into layers was retired from extraction, and where layers survive (the layer field on Permanent Notes)

Solutions:

• The Extraction Pipeline — Ingest → Extract → Index, with an admission gate before extraction
• The Autonomous Research Loop — Filling knowledge gaps through targeted multi-round web research (a practice)

---

Module 3: Knowledge Maturation

How captured notes become your own ideas. The promotion process that separates storage from understanding.

Problems:

• The Literature Note Graveyard — 500 notes from 20 books, but no original positions
• Premature Synthesis — Building theses on thin evidence before sufficient convergence
• Domain Blindness — Not knowing what you know or what you're missing in a field
• Convergence Detection — Why two independent sources confirming an idea beat ten that merely mention it
• The Endorsement Gap — The difference between a note that exists in your vault and one you have explicitly approved

Solutions:

• The Maturation Ladder — Literature Note → Your Extension → Convergence → Permanent Note → Domain Synthesis, with maturity (seed → growing → evergreen) derived from use afterwards
• Convergence Promotion — The 4-part convergence test, the per-cluster extension gate, and the state machine from draft to endorsed (plus visual pattern promotion)

---

Module 4: Active Recall & Practice

How knowledge becomes skill. The practice layer that closes the gap between understanding and doing.

Problems:

• The Collector's Fallacy — When saving notes feels like learning but produces no retention
• Skill Stagnation — The gap between understanding a concept and actually doing it well
• Invisible Progress — Learning without a feedback loop: you don't know if you're improving
• Course Gate Design — Why linear reading produces recognition but not generation or transfer
• Context-Absent Output — When AI generates answers without grounding in your actual knowledge
• The Judgment Gap — The distance between knowing about X and having developed judgment on X
• Empty Prompting — Using AI as a content dispenser without building judgment: outputs accumulate, capability stays flat

Solutions:

• The AI-Driven Creation Loop — Delegate → Elevate → Challenge as a practice you run by hand, and the loop the skills run: practice log → gaps and friction → promotion review → next course
• The Specificity Delta — Comparing an output made without your vault against one made with it (a manual comparison)
• The Learning Science of Courses — The research behind the course design
• Three-Gate Progression — Vocabulary → Production → Transfer, scored after the course by a separate evaluation step

---

Module 5: Knowledge Retrieval

How to access what you know — in multiple modes, for different purposes, from any context.

Problems:

• The Search Box Bottleneck — Why text search degrades as the primary retrieval method for complex knowledge
• Isolated Retrieval — Finding individual notes without following the reasoning thread connecting them
• Knowledge Portability — When your vault is stranded on your laptop and inaccessible everywhere else

Solution:

• Multi-Modal Retrieval — Six intents (including a visual track), a query-expansion gate, one-hop graph traversal, and remote access as a read-only search-and-read pattern

---

Module 6: Vault Health & Maintenance

How to keep a