qcobrain

# qcobrain

> qcobrain is the co-brain that cites its sources: an open-source, self-evolving, provenance-governed second brain you clone straight into your IDE. Its core thesis is cite-or-refuse (provenance-or-silence) — every write, whether by a human or by an autonomous loop, must trace to a verbatim quote in a real source or it is structurally refused, never written as an unsourced "fact." Sourced facts compound; hallucinations get refused at the gate, so the brain grows more trustworthy instead of quietly rotting.

qcobrain is plain markdown + grep — no database, no server, no embeddings, no lock-in — so any human or model can read, diff, and `grep` the entire brain with the tools already in a terminal. It is model-agnostic by design: a single file, [AGENTS.md](AGENTS.md), lets any model open the folder cold and operate it correctly. And it is open-core — the core needs zero external services, with an optional, off-by-default agent layer (the Quarktex relay) you can delete without affecting core.

## Start here
- [README](README.md): The human-facing overview — what a co-brain is, the architecture at a glance, the skills, and the directory layout.
- [Getting started](docs/getting-started.md): A hands-on day-1 walkthrough — clone, onboard, capture your first source, recall a cited answer, and watch the integrity check go green.
- [AGENTS.md](AGENTS.md): The model-agnostic operating contract — the per-session read order, the prime directive, the write protocol, and the update cadence any agent follows.

## Core concepts
- [Architecture](ARCHITECTURE.md): How the brain is shaped — the four concerns (substrate, evolution, retrieval, capabilities) and why the design holds together.
- [Concepts](docs/concepts.md): The single mental model — cite-or-refuse, the provenance chain, the write-origin flag, and the three-brain separation.
- [Positioning](docs/positioning.md): The category qcobrain owns — provenance-governed AI memory — the problem it kills, and what makes it different.
- [Kernel](references/kernel.md): The provenance contract every skill inherits, stated verbatim. The law.
- [Wiki spec](references/wiki-spec.md): The storage schema — note frontmatter, the `src` citation block, the sources registry, and the derived index format.

## Skills
- [Skills reference](docs/skills.md): Every skill — what it does, when to reach for it, what it reads and writes, with a worked example each.
- [Capability registry](skills/INDEX.md): The runnable-skill registry — look here first when you need to do something or you're stuck.

## Optional
- [Agent layer](docs/agent-layer.md): The optional, off-by-default remote-agent relay — setup, the wire contract, and the trust boundary that keeps a returned answer governed by cite-or-refuse.

## Meta
- [Docs index](docs/index.md): The full, hand-maintained table of contents for every doc in the repo.
- [Contributing](CONTRIBUTING.md): How to propose changes; the one non-negotiable is that every write honors cite-or-refuse.
- [Security](SECURITY.md): What stays local vs. leaves your machine, secret handling, and private disclosure.
- [Changelog](CHANGELOG.md): Notable changes to qcobrain, release by release.
- [License](LICENSE): MIT, © 2026 Quarktex.