Most second brains store information.
This one decides what deserves to become knowledge.
It turns evidence from the tools you already use into claims, routes every claim through a deterministic governance protocol instead of vibes, and only then lets something become durable knowledge an AI agent can use with provenance. Then it compiles the right slice of that knowledge into task-scoped context - always showing you what it left out and why.
Evidence -> Claims -> Governance (KEP) -> Durable Knowledge -> Compiled Context
Evidence is collected. Knowledge is governed. Context is compiled. Those are three distinct steps with three distinct trust levels, and this project never lets them blur into one.
This is not a RAG pipeline, a vector database, an Obsidian template, or a prompt collection. There's no embedding search here at all - retrieval is "which durable, approved notes match this task," not "which chunks are semantically similar." The interesting part isn't storage; it's the governance step in the middle that decides what's allowed to become knowledge in the first place.
git clone https://github.com/alfielambert/second-brain.git
cd second-brain
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
second-brain init ~/my-vault --with-sample
cd ~/my-vault
second-brain claims # 9 claims from a fictional company (Acme)
second-brain route # KEP decides: auto-apply, propose, or signal
second-brain claims # 1 auto-applied, 7 need approval, 1 weak signal
second-brain approve --all-pending # approve everything (real usage: review each one)
second-brain compile --target founder
cat Packs/founder.md # a compiled context pack, with a Compile ReportNo API keys required for this loop - it's the deterministic core end to
end, using a fictional dataset (a company called Acme, evaluating a
product called Atlas) that deliberately includes a contradiction: an
early "launch in September" decision gets superseded by a later one
once you approve it, and you can watch Decisions/Atlas Launch Date.md
record exactly why.
Any tool can save a note. The hard part is deciding what should become knowledge an agent is allowed to act on. This project's answer is KEP (Knowledge Evolution Protocol) - a deterministic lookup table, not a model call, that decides whether a new claim gets written automatically, held for your approval, or logged as a weak signal that doesn't yet earn a place in the vault:
| the claim is... | KEP does... |
|---|---|
| a high-confidence update to something that already exists | auto-applies it |
| a new entity, a contradiction, a decision change, anything structural | always asks you first |
| weak or low-confidence | logs it as a signal, never proposes it |
Nothing is ever silently overwritten. Claims are append-only; a claim's
current status is derived by replaying its governance events, not by
mutating the record - so you can always answer "why does the vault say
this" by walking the chain back to the original evidence. See
docs/claim-store-and-kep.md.
Local mode runs everything on your machine and needs nothing beyond this repo. Multiplayer mode adds OpenLore at the end, once more than one agent needs the same knowledge.
OpenLore is an open-source knowledge server for AI agents. Second Brain creates and governs knowledge. OpenLore distributes governed knowledge to agents. The two are cleanly separable, and OpenLore is entirely optional - you do not need it to build or use the Second Brain locally. Everything in the quickstart above works identically whether or not OpenLore is ever configured.
Once several agents need the same current knowledge, maintaining separate
copies creates a new problem: context starts to diverge. OpenLore is the
distribution layer that keeps one governed knowledge base available to
multiple agents, serving the vault's governed directory live with no
separate publish step - see
docs/openlore-integration.md.
Full diagram, the reliability layer (bounded connector sessions, safe
retries, health vs. execution status, the notification outbox, the
watchdog), and the local-core/Claude-Code-runtime split:
docs/architecture.md.
The deterministic core (second_brain/ - Claim Store, KEP, connector
state, locking, safe writes) is plain Python with no model dependency at
all. The automated reasoning layer - deciding what a bookmark or email
actually means, orchestrating a daily sync, writing real prose into a
compiled pack - is Claude Code-native in v1. That's a stated design
choice, not a hidden limitation: see
claude/README.md for exactly where that line is and
what a future non-Claude runtime would need to implement.
x_bookmarks(flagship) - real OAuth 2.0 PKCE against the live X API, incremental sync, no MCP dependency. Works with your own X developer app.capture- the simplest connector: drop a.md/.txtfile inClaimStore/captures/inbox/, get a claim.- Gmail, Calendar, Notion patterns are documented (not shipped as code)
in
docs/connector-contract.md- they depend on your own MCP account grants, so shipping "working" code for them would only really work for one person.
Writing your own: docs/connector-contract.md.
second-brain init ~/my-vault(no--with-samplethis time)- Enable
capture(already on by default) and drop a real note inClaimStore/captures/inbox/ second-brain sync --connector capture && second-brain route- When you're ready for something automated: set up
x_bookmarks(docs/connector-contract.md), then the Claude Code layer for real judgement-based extraction (claude/README.md), then scheduling (launchd/README.md) - Once Claude Code, ChatGPT where supported, and other MCP-capable agents
all need the same current knowledge, see
docs/openlore-integration.md
MIT. See LICENSE.
