https://github.com/jeremylongshore/governed-second-brain-plugin
Governed Second Brain — a local-first, in-process Claude Code + Cowork plugin. Turn your own files into cited (qmd://) memory with a tamper-evident, SHA-256 hash-chained audit trail. No daemon, no network.
https://github.com/jeremylongshore/governed-second-brain-plugin
audit-trail citations claude-code cowork governance governed-second-brain knowledge-management local-first mcp plugin qmd rag second-brain
Last synced: 1 day ago
JSON representation
Governed Second Brain — a local-first, in-process Claude Code + Cowork plugin. Turn your own files into cited (qmd://) memory with a tamper-evident, SHA-256 hash-chained audit trail. No daemon, no network.
- Host: GitHub
- URL: https://github.com/jeremylongshore/governed-second-brain-plugin
- Owner: jeremylongshore
- License: apache-2.0
- Created: 2026-06-17T00:58:55.000Z (13 days ago)
- Default Branch: main
- Last Pushed: 2026-06-25T18:26:45.000Z (4 days ago)
- Last Synced: 2026-06-25T20:13:02.145Z (4 days ago)
- Topics: audit-trail, citations, claude-code, cowork, governance, governed-second-brain, knowledge-management, local-first, mcp, plugin, qmd, rag, second-brain
- Language: JavaScript
- Size: 581 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Governed Second Brain — the plugin
A local-first Claude Code + Cowork plugin: turn your own files into a governed,
qmd://-cited second brain with a tamper-evident, SHA-256 hash-chained audit trail.
Compile, then govern. One plugin, two modes: local (default — in-process, no daemon, no network, no API key for retrieval) or team (proxy to a shared governed brain over your network).
---
## 📍 This product lives in two homes
| | Repo | What it is |
|---|---|---|
| **Landing / thesis** | **[intent-solutions-io/governed-second-brain](https://github.com/intent-solutions-io/governed-second-brain)** | The umbrella — *why* this exists, the competitive teardown, the "Compile, Then Govern" thesis, the receipts argument. Start here for the **story**. |
| **The plugin** (you are here) | **[jeremylongshore/governed-second-brain-plugin](https://github.com/jeremylongshore/governed-second-brain-plugin)** | The installable code — the local stdio MCP server + skills. Start here to **run it**. |
It stacks on three engines:
| Engine | Repo | Layer |
|---|---|---|
| **ICO** | [jeremylongshore/intentional-cognition-os](https://github.com/jeremylongshore/intentional-cognition-os) | **Compile** — derive knowledge from a corpus (optional; the only part that egresses) |
| **INTKB** | [jeremylongshore/qmd-team-intent-kb](https://github.com/jeremylongshore/qmd-team-intent-kb) | **Govern** — deterministic dedupe → policy → promote + the hash-chained audit |
| **qmd** | [tobi/qmd](https://github.com/tobi/qmd) | **Retrieve** — on-device search; every hit is a `qmd://` citation |
This plugin **bundles** the compiled INTKB packages, so it runs the govern + retrieve loop fully
in-process — the engines stay independent repos; nothing here forks or privatizes them.
## What it does
Most "AI memory" gives an agent better *recall*. This does two things the category skips: it
**governs** what's allowed to become durable memory (deterministic dedupe / policy / promotion — by
code, not a model), and it ships a **receipt** — a `qmd://` citation plus a SHA-256 hash-chained audit
event — for every write. Runs on your machine; your files never leave it (retrieval is local; the
optional ICO *compile* step is the only thing that egresses, and it's opt-in).
### Tool surface
| Tool | Kind | What it does |
|---|---|---|
| `brain_search` | read | Cited search over your governed memory (`qmd://` receipts), in-process |
| `brain_status` | read | Counts by lifecycle state + category |
| `brain_audit_verify` | read | Verify the audit trail — the SHA-256 hash chain **and** the external anchor log; flags any tamper |
| `brain_capture` | write | Capture a fact as a governance **proposal** (to the local spool) |
| `brain_govern` | write | Drain the spool → dedupe → policy → **promote**, with a hash-chained audit receipt — daemon-free |
| `brain_transition` | write | Retire / re-lifecycle a memory (audited) |
Two skills front these: **`/brain`** (cited answers) and **`/brain-save`** (governed capture).
## What the receipt does *not* do
Honesty is the point of a receipt. The chain gives you **tamper-*detection*** — integrity + ordering,
so an edited or reordered record is caught by `verify`. It is **not** tamper-proof: on your own machine
a writer with access can edit an event *and* re-hash the chain forward. Within a single trust boundary
(your machine) that's exactly the integrity guarantee you want; cross-actor non-repudiation needs an
external chain-head anchor (on the roadmap). It is **not** a blockchain and **not** immutable storage.
## Install
One command, two modes:
```bash
# A) zero-egress (default for regulated/client data) — nothing leaves the machine
npx governed-second-brain init --index-only
# B) full compile — ICO derives knowledge (6 passes) before governing; opt-in egress to DeepSeek
DEEPSEEK_API_KEY=… npx governed-second-brain init
```
It builds a governed, `qmd://`-cited, hash-chained-audited brain under `~/.teamkb`, installs the native
dep per-platform, and **auto-registers the MCP server with Claude Code** (`claude mcp add`; `--no-register`
to skip). Full mode runs a loud pre-flight consent (your file text goes to DeepSeek; `--yes` to skip the
prompt). Requires Node 20+, a C/C++ toolchain (for `better-sqlite3`), and `qmd` 2.x on PATH for retrieval.
After it finishes, start a new Claude Code session — the `governed-brain` tools are live. For the
`/brain` and `/brain-save` skills too, `claude plugin install governed-second-brain`.
### Team mode — point it at a shared brain
The **same** plugin runs in **team mode** when `TEAMKB_API_URL` is set: instead of an in-process local
brain, it proxies to a shared governed-brain HTTP API (INTKB's `apps/api`) over your network — so a
whole team queries and contributes to **one** governed brain. Set two environment variables:
- **`TEAMKB_API_URL`** — your team brain's API base (e.g. `http://:3847`)
- **`TEAMKB_API_TOKEN`** — your personal bearer token (issued by the brain's operator)
You need network reachability to that API — typically a private network / VPN such as **Tailscale**
(the brain is meant to stay off the public internet). The dispatcher auto-detects mode from
`TEAMKB_API_URL`: set → team, unset → local. Same `/brain` + `/brain-save` skills either way.
In team mode the tool surface is **`brain_search`** (read) + **`brain_capture`** (propose) +
**`brain_transition`** (admin-only) — govern runs server-side, so there's no client `brain_govern`:
**the model proposes, the server disposes**, and each promotion gets a hash-chained receipt. A member
token can read + propose; admin actions (transition) return a clear 403 otherwise.
> Team mode is **dependency-free** — it uses only `fetch` + the MCP SDK, never the native store — so it
> runs straight from a marketplace clone with zero build.
Build from source (to hack on the runtime)
```bash
pnpm -C ../qmd-team-intent-kb build # the bundle inlines INTKB's compiled packages (sibling checkout, built)
pnpm install && pnpm build # esbuild → plugin-runtime/governed-brain.cjs
node bin/init.mjs init --index-only
```
**Supply chain (shipped in 0.1.4):** npm **provenance** (via the CI release workflow) and the
`gsb.lock.json` reproducible pin — the exact ICO × INTKB × qmd × plugin tuple, verified by a
hermetic full-chain CI smoke against the pinned set.
**Coming:** automatic Cowork MCP registration.
## License
Apache-2.0. The umbrella and both engine repos are Apache-2.0; qmd (upstream) is MIT by its author,
[@tobi](https://github.com/tobi).
---
Built by Jeremy Longshore ·
Intent Solutions ·
thesis at intent-solutions-io/governed-second-brain