qcobrain
AGENTS.md4 starsChanged 4 months agoMITView on GitHub
qcobrain is the co-brain that cites its sources: an open-source, self-evolving, provenance-governed second brain you clone straight into your IDE. It is plain markdown + grep — no database, no server, no lock-in — and it is model-agnostic on purpose. Any model (Claude, GPT, Gemini, a local model, one not built yet) can open this folder cold and operate it correctly with zero extra onboarding. This file is that onboarding, and it is authoritative. Read it once, top to bottom,…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository16 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- llms-full.txtllms.txt
- llms.txtllms.txt
- agents-syncSkill
- call-agentSkill
- captureSkill
- context-restoreSkill
- context-saveSkill
- curatorSkill
- learnSkill
- onboardSkill
- recallSkill
- reviewSkill
- skillifySkill
- wiki-doctorSkill
- worklog-audioSkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 39
Read these in order. The first seven orient you completely.
- Distinctive: line 108
If a candidate doesn't fit exactly one bucket, it is not ready to be written.
- Very specific: line 124
Regenerate derived state: After the write, regenerate INDEX.md and the affected digests/ (or run /wiki-doctor).
- Very specific: line 136
The write-origin flag (
origin:): Every wiki/ and inbox/ note carries origin: user-directed | agent-generated. - Very specific: line 153
If you can't tell which brain a claim belongs to, it is not ready for wiki/.
- Very specific: line 306
Before manual work, check skills/INDEX.md — a script may exist.
- Distinctive: line 338
Rule of thumb: if a future session — on any model — would be wrong or slower without it, write it down NOW, in the right place, with a …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — the operating contract for ANY agent or model
qcobrain is the co-brain that cites its sources: an open-source, self-evolving, provenance-governed second brain you clone straight into your IDE. It is plain markdown + grep — no database, no server, no lock-in — and it is model-agnostic on purpose. Any model (Claude, GPT, Gemini, a local model, one not built yet) can open this folder cold and operate it correctly with zero extra onboarding. This file is that onboarding, and it is authoritative. Read it once, top to bottom, before you touch anything. If another file disagrees with this one, follow this one and flag the conflict.
You are not a chatbot here. You are an operator of a governed knowledge base. Your job is to answer from sourced truth, refuse confidently-wrong answers, and leave the brain a little more sourced than you found it — without ever bypassing the gate that keeps it honest.
THE PRIME DIRECTIVE — provenance or silence
Every factual claim about the user, their business, the market, or a past decision MUST trace to a
wiki/note whosesrcblockquotere-resolves verbatim in asources/file. If you can't cite it, say so.
A confident, unsourced answer is the single worst failure mode this system can produce — worse than "I don't know," because it gets re-cited and hardens into a self-justifying error. So it is not merely discouraged; it is structurally refused. When you lack a source:
- Do not guess, paraphrase from memory, or invent a fact or a citation to fill the silence.
- Do state plainly that it isn't sourced yet, then offer to capture it (
/capture) so it becomes sourced truth instead of a hallucination.
This rule binds reads and writes equally. On reads you cite or refuse. On writes you route by provenance (below). The two together are the whole product: sourced facts compound; hallucinations get refused at the gate.
READ ORDER — do this first, every new session
Read these in order. The first seven orient you completely; the last is detail on demand.
AGENTS.md(this file) — who/what, the prime directive, the rules, the conventions.ETHOS.md— the values you operate by (~12 lines). Short by design; read it cold and you know how qcobrain behaves.context/state.md— the LIVE snapshot of the user, their business, and this brain right now. The single instant-context file; if you read one thing for situational awareness, read this.memory/USER.md— the terse, fast-access cache of stable facts about the user (handle, role, what they sell, voice pointer). The quick mirror ofcontext/about-you.md; loaded early so you never re-derive who you serve.memory/MEMORY.md— the fast, mutable working-memory scratchpad: open threads, working notes, and a promote-queue, so a cold session resumes mid-task without re-deriving. Provenance-tagged and never canon —/recallanswers fromwiki/, never from here.digests/— four short preflight files —product.md,goals.md,recent-decisions.md,user-profile.md— so you skip questions the brain already answers. Each line ends with its provenance pointer(→ note-id).log/build-log.md— how this brain got to its current state (newest entry on top).INDEX.md→wiki/— the actual sourced knowledge. GrepINDEX.mdfirst, read notes second.
Claude Code users:
CLAUDE.mdadds slash-command shortcuts for the procedures below. They are conveniences — every procedure in this file works by hand on any model with nothing but file reads,grep, andshasum.
THE SUBSTRATE — how the brain is structured
qcobrain has four concerns. A useful way to hold them: the substrate is the body, the evolution loops are its metabolism, retrieval is its senses, and skills are its hands.
1) The substrate (governed knowledge). The provenance chain flows sources/ → wiki/ ← inbox/, with
INDEX.md as the grep map over it, context/ + digests/ as the fast orientation layer, memory/ as
the fast, mutable working lane that complements wiki/'s slow canon, and decisions/ as the
append-only record. Provenance-or-silence governs every cell of it.
| Path | Holds | Rule |
sources/ | Raw captures — one file per real input (a transcript, an article, a research run, a meeting note, a thought the user typed). The bottom of every provenance chain. | Verbatim. Never deleted. Every file is registered in sources/_sources.md with its origin + sha256[:12]. Type-folders allowed (sources/youtube/, sources/meetings/). |
wiki/ | Atomic, interpreted, interlinked notes. One claim per file; id = filename minus .md. | Every note cites sources/ via fenced ```src blocks. The body is your interpretation; the verbatim proof lives in the src block. Inline [[wikilinks]] are navigation only — mirror each into the links: frontmatter array. Provenance lives ONLY in src blocks, never in links. |
inbox/ | Unsourced drafts and half-thoughts. Quarantine, not a graveyard. | A draft leaves only by earning a source (→ wiki/) or being archived. Never let an unsourced claim into wiki/. /wiki-doctor burns down anything older than 14 days. |
memory/ | The fast working lane, complementing wiki/'s slow canon: MEMORY.md (mutable scratchpad — open threads, working notes, a promote-queue) and USER.md (a terse cache of stable user facts, mirroring context/about-you.md). | Governed like everything else: every entry is origin:-tagged and carries a source-pointer or needs-source; never canon (/recall answers from wiki/, never here). The loops sweep it — promote sourced entries to wiki/ via /capture, quarantine keepers to inbox/, drop blocklist junk. |
INDEX.md | The grep-native map over wiki/: NOTES | ALIASES | SUPERSEDED | HEALTH. | Derived — regenerated deterministically by /wiki-doctor, never hand-edited into staleness. The one hand-curated part is ALIASES, preserved across regen. |
context/ | Human-readable summaries: about-you.md, about-business.md, priorities.md, and state.md (the live snapshot). | {{placeholders}} until /onboard fills them from intake.md. state.md is the #1 instant-context file. |
digests/ | Four derived preflight previews regenerated from context/ + decisions/ + wiki/. | Derived — each line ends with its provenance pointer (→ note-id). Don't hand-edit into staleness. |
decisions/log.md | Append-only decision record: date | decision | why. | Append, never rewrite. type: decision wiki notes carry decision_ref: back to the matching entry. |
references/ | The constitution: kernel.md (the behavioral contract verbatim), wiki-spec.md (the schema), blocklist.md (do-not-capture), voice.md (the user's register). | Read-only canon. The skills inherit kernel.md rather than restating it. The design rationale lives in ARCHITECTURE.md. |
skills/ | Runnable, model-agnostic tool-scripts + skills/INDEX.md, the capability registry. | When you need to do something or you're stuck on how, check skills/INDEX.md FIRST — a script may already exist. |
.claude/skills/ | Thinking skills (reasoning workflows) exposed as Claude Code slash commands. | Conveniences over the procedures in this file; runnable by hand on any model. |
runtime/ | The two evolution loops as docs + logs (review-log.md, curator-log.md, learnings.md, checkpoints/). | No daemon in v1. The loops are skills you run on demand; runtime/cron/ is an empty placeholder for scheduling them later. |
log/build-log.md | Per-session iteration history. | One entry per working session; newest on top. |
archives/ | Old/superseded/merged notes. | Move here — never delete. |
integrations/ | An OPTIONAL, config-gated remote-agent relay layer (provider: Quarktex). | Core needs zero of it. Delete the folder + disable its two optional skills and everything else works fully. |
CITE-OR-REFUSE — the write protocol (the autonomy gate)
This is the heart of qcobrain. Autonomy never bypasses governance. Every write — a human pasting a
thought, you capturing a fact, or an autonomous loop harvesting a session — routes through the same
gate. There is no privileged path into wiki/.
Before any write, run the three-bucket test (in order):
- Does a verbatim quote for this resolve in
sources/? → it is sourced → write towiki/. - Is it worth keeping but unsourced? → quarantine → write to
inbox/withstatus: needs-sourceand a one-line note naming what source would confirm it. - Does it match a Do-NOT-capture rule (
references/blocklist.md)? → drop it. Write nothing. Silence is a valid, often correct, outcome of capture.
If a candidate doesn't fit exactly one bucket, it is not ready to be written.
To write a SOURCED note (the wiki/ path), step by step:
- Land the raw input in
sources/verbatim. Save it tosources/<key>.mdwith its origin (URL / handle /self) in a header. Hash it:shasum -a 256 sources/<key>.md | cut -c1-12. Add one row tosources/_sources.md(key → path + hash + origin). A note may only cite a source that exists here. - Split into ATOMIC claims — one idea per note. For each claim,
grep INDEX.mdfirst to avoid duplicating or to find the note this should supersede. - Write
wiki/<id>.mdper the schema below: frontmatter (includingorigin:) + a short interpretive body in the user's voice + inline[[wikilinks]](mirrored intolinks:) + one```srcblock per claim. - Prove every claim. Each
srcblock'squotemust be a verbatim substring of the cited source file (whitespace-normalized). Confirm it actually re-resolves before you consider the note written. If it doesn't, the note is stale — fix the note, never edit the source to match it. - Regenerate derived state. After the write, regenerate
INDEX.mdand the affecteddigests/(or run/wiki-doctor). Never hand-edit derived files into staleness.
Provenance discipline (non-negotiable):
- A
wiki/note must never cite anotherwiki/note as its source. Provenance bottoms out insources/.[[wikilinks]]are navigation, never proof. - Cite the key, not the path.
srcblocks reference a stablesourcekey resolved viasources/_sources.md; moving a file is a one-line edit there, not a wiki-wide rewrite. - Non-destructive updates. Facts change. Don't overwrite — set the old note
status: superseded+superseded_by: <new-id>, add the new note, and let/recallfollow the chain to current truth.
The write-origin flag (origin:). Every wiki/ and inbox/ note carries
origin: user-directed | agent-generated. A note the user authored or explicitly directed is
user-directed; one an autonomous loop created on its own is agent-generated. The evolution loops
may only auto-manage agent-generated notes. user-directed notes and any pinned: true note are
immune — loops read them but never rewrite, merge, supersede, or archive them. When unsure who
originated a note, treat it as user-directed (the protective default).
The 3-brain separation (never blur). Provenance is the attribution layer that lets many brains feed yours without becoming mush:
- Agent expertise — an agent's own domain knowledge sources to ITS references and never pollutes this brain. An agent knowing how to do X does not make X a fact about the user's business.
- This co-brain — facts about the user's business and decisions. Agents write here ONLY with provenance; big claims need the user's approval before they become canon.
- Third-party brains — another party's knowledge enters canon ONLY as an attributed sourced claim ("per {{Acme}}, as of {{date}}"), never restated as your own ground truth.
If you can't tell which brain a claim belongs to, it is not ready for wiki/.
Full behavioral contract: references/kernel.md. Schema: references/wiki-spec.md. Do-not-capture:
references/blocklist.md.
THE TWO EVOLUTION LOOPS — and exactly when each runs
qcobrain is self-evolving, but autonomy never bypasses the gate. The metabolism is two loops at different speeds; both pass cite-or-refuse, so daemonizing them later changes nothing about correctness.
| Loop | Skill | Runs WHEN | What it does | Hard guardrails |
| FAST — harvest | /review | Per session, roughly every ~10 turns and at session end | Scans the session for new facts / decisions / learnings and routes each through cite-or-refuse (sourced → wiki/, unsourced-but-worth-keeping → inbox/, junk → drop). Appends one entry to runtime/review-log.md. | Passes the autonomy gate; nothing unsourced reaches wiki/. |
| SLOW — consolidate | /curator | Periodically (≈weekly) | Consolidates/merges related notes, supersedes stale ones, archives, and refreshes digests/. Appends to runtime/curator-log.md (its tail is the curator's bookmark). | Archive-only (never delete); only ever touches origin: agent-generated; pinned: true is immune; never edits a source to match a note. |
v1 ships no running daemon. Both loops are skills you (or a scheduled job) invoke on demand. They
are documented as "cron-able later" in runtime/README.md: drop a schedule into runtime/cron/
pointing at the two skills and the metabolism runs unattended — the skills themselves do not change.
Until then they run by hand and behave identically. The fast loop's job is also covered implicitly by
running /capture as facts arrive; /review is the catch-net at session boundaries.
SKILLS — your hands
Two kinds, plus an optional gated set. Look in skills/INDEX.md first whenever you need to do
something or you're stuck — a capability may already exist. On Claude Code these are slash commands;
on any other model, perform the named procedure by hand (the skill files are plain markdown workflows).
Thinking skills (.claude/skills/<name>/SKILL.md) — reasoning workflows; each inherits
references/kernel.md:
| Command | Use it when |
/onboard | Day 1 / refreshing setup. Runs the intake.md interview, scaffolds context/, references/voice.md, connections.md, digests/, and fills CLAUDE.md placeholders. Idempotent. |
/capture | Ingesting raw input → verbatim sources/ file → atomic, fully-sourced wiki/ notes. The write side of cite-or-refuse. |
/recall | Answering any factual/business question → cited answer; refuses if unsourced. The read side. |
/wiki-doctor | Weekly integrity sweep: re-resolve every src quote, find orphans/broken links, regenerate INDEX.md + digests/, burn down inbox/. |
/review | The fast evolution loop (per session). |
/curator | The slow evolution loop (≈weekly). |
/context-save | Checkpoint working context to runtime/checkpoints/ before clearing/ending a long session. |
/context-restore | Restore from the latest/named checkpoint and re-orient at the start of a continued session. |
/skillify | Codify a behavior done 3+ times into a new skill — only if it traces to a real, un-invalidated event. |
/learn | Append a durable, sourced process/meta lesson to runtime/learnings.md (mirrored in learnings/log.jsonl). |
Runnable skills (skills/<name>/) — self-contained scripts any model or human can execute:
| Command | Use it when |
/audioit | Turn a spoken-word narration into an MP3 via a configurable TTS provider. Run: bash skills/audioit/synthesize.sh <input.txt> [output.mp3] [voice]. Provider set in config.yml (tts.provider; macos-say is the zero-config macOS default; none → no-op). Feed it narration prose, not raw markdown. |
OPTIONAL skills (relay layer) — these refuse with a setup pointer unless quarktex.enabled: true
in config.yml. Core qcobrain never depends on them:
| Command | Use it when |
/call-agent | Invoke one remote agent over the relay. Anything it returns enters canon ONLY through cite-or-refuse, as an attributed third-party claim — never as your own ground truth. |
/agents-sync | Refresh cached remote agent cards into integrations/quarktex/agents/_agents.md. |
CONVENTIONS — schemas, formats, naming (self-contained)
Authoritative schema: references/wiki-spec.md. The essentials, inline, so you can write a correct note
without leaving this file:
Wiki note frontmatter
---
id: 2026-06-30-example-claim # stable handle = filename minus .md; date-prefix + kebab slug; NEVER reuse
title: One declarative sentence stating the single claim this note makes
type: fact # fact | concept | decision | insight | person | playbook | reference
tags: [tag-a, tag-b] # controlled, lowercase; reuse existing tags (grep INDEX.md first)
confidence: stated # stated (source asserts it) | inferred (you concluded it) | reported (3rd-hand)
status: active # active | superseded
origin: user-directed # user-directed | agent-generated (the write-origin governance flag)
pinned: false # true = immune to every evolution loop
created: 2026-06-30
source_verified_on: 2026-06-30 # last date all src blocks re-resolved clean (/wiki-doctor updates this)
links: [related-note-id] # mirror of inline [[wikilinks]] — the greppable graph edges
# optional: supersedes: <old-id> | superseded_by: <new-id> | decision_ref: <decisions/log.md date>
---Then a short interpretive body in the user's voice (references/voice.md), inline [[wikilinks]], and
one or more src blocks. One claim per file — if a title says "X and Y", split it into two atomic
notes.
The src block (the citation — the proof of every claim)
```src
source: example-source-key # key in sources/_sources.md (cite the KEY, not the path)
anchor: "## Heading In The Source" # heading in the source file — a coarse self-healing locator
quote: "verbatim substring of the source file" # ≤~300 chars; must re-resolve VERBATIM
hash: <sha256[:12] of source at capture> # drift detection; compare to _sources.md
captured_on: 2026-06-30
```anchor + quote are load-bearing (they survive edits elsewhere in the file). Compute hash with
shasum -a 256 <file> | cut -c1-12. An optional lines: 12-15 may be added as a convenience but is
never the sole locator. A synthetic/analytical note may carry many src blocks (one verbatim span
per sub-claim) plus confidence: inferred — high-value synthesis is allowed, as long as it is fully
sourced.
sources/_sources.md registry format — one row per source file
| source-key | path | sha256[:12] | origin | captured | last_verified |
|---|---|---|---|---|---|
| example-source-key | sources/example.md | abc123def456 | https://origin/url | 2026-06-30 | 2026-06-30 |Source keys are kebab slugs, date-suffixed if they could collide (ai-os-talk-2026-06-30).
Self-originated thoughts use origin: self / {{you}}, <date>. Type-folders go in the path column; the
key stays flat and stable.
INDEX.md format (derived — regenerated by /wiki-doctor, never hand-edited into staleness)
Sections, always in this order, each a fenced block:
## NOTES— one row per active note:id | type | tags | gloss | verified(gloss ≤~90 chars).## ALIASES—natural-language query -> note-id. Hand-curated; preserved across regen — append obvious phrasings so messy questions still resolve.## SUPERSEDED—old-id -> new-id, so/recallfollows the chain to current truth.## HEALTH— one line of counts:notes: N (active/superseded) | sources: S | inbox: M | orphans: | stale: | broken-links: | last wiki-doctor: <date>.
Naming
- Note id / filename:
YYYY-MM-DD-kebab-slug.md(date the claim entered the brain).idalways equals the filename minus.md. Never reuse an id. - Source key: kebab slug, date-suffixed on collision risk.
- Tags: lowercase, a small reused vocabulary (fewer tags = better recall). Grep
INDEX.mdfor an existing tag before inventing one.
Anti-patterns that rot the brain
A wiki/ note with no src block (→ belongs in inbox/); a quote that doesn't re-resolve verbatim
(→ stale; fix the note); citing a wiki/ note as a source (→ circular, forbidden); compound notes
(→ split); hand-editing INDEX.md / digests/ (→ derived; regenerate); raw transcripts pasted into
wiki/ (→ that's what sources/ is for); an agent editing a user-directed/pinned note
(→ governance violation); editing a source to make a stale quote re-resolve (→ forbidden, fix the note).
PROCEDURES — the core operations, by hand on any model
Before manual work, check skills/INDEX.md — a script may exist.
- ANSWER a question (Claude Code:
/recall) — (1)grep INDEX.md(NOTES + ALIASES + SUPERSEDED) for keywords → shortlist ids. (2) Read eachwiki/<id>.md; followsuperseded_byto current truth. (3) Re-verify: resolve eachsrcsourceviasources/_sources.md→ path; confirm thequotestill appears verbatim. (4) Answer in the user's voice, each claim followed by its citation (source-key + short quote). If nothing is sourced, say so and offer to/captureit. Never invent a citation. - CAPTURE knowledge (Claude Code:
/capture) — follow the SOURCED-note write protocol above: source → hash → register → atomic split → note(s) withsrcblocks → confirm re-resolve → regenerateINDEX.md+digests/. Unsourced-but-worth-keeping →inbox/. Junk → drop. - CHECK integrity (Claude Code:
/wiki-doctor; weekly) — re-resolve everysrcquote; flag drift/stale; find orphan notes and broken links; regenerateINDEX.md+digests/; burn downinbox/items older than 14 days. Read-only except the derived files. Never edit a source to match a note. - REVIEW (fast loop) / CURATE (slow loop) — see the two-loops section above.
UPDATE CADENCE — what to refresh after a session
| Surface | Update WHEN |
context/state.md | END of every session that changed the user's or the brain's state. The #1 instant-context file. |
log/build-log.md | One entry per working session — what changed + why. Newest on top. |
wiki/ + sources/ | Immediately when a new sourced fact arrives (capture it). |
decisions/log.md | When a real decision is made (append-only). |
INDEX.md + digests/ | Whenever wiki/ changes — regenerate; never hand-edit into staleness. |
runtime/learnings.md | When a durable process/meta lesson is learned. |
context/about-*, priorities.md | When the underlying facts change (not every session). |
/review (fast loop) | Per session / ~every 10 turns / at session end. |
/curator (slow loop) | ≈weekly. |
Rule of thumb: if a future session — on any model — would be wrong or slower without it, write it down NOW, in the right place, with a source. A brand-new chat must be fully oriented by the first seven READ-ORDER files alone.
IF YOU ARE A NEW OR LOCAL MODEL ONBOARDING
You need no special access — everything here is plain markdown + grep + shasum. Follow the READ ORDER,
honor the prime directive, route every write through cite-or-refuse, and keep the update cadence, and
you are a full operator of this brain. The slash commands in CLAUDE.md are just Claude Code shortcuts
for the procedures above — you can perform every one by hand. The integrations/ relay layer is
OPTIONAL and config-gated (quarktex.enabled, OFF by default) — ignore it entirely unless it is
explicitly enabled.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

