{
  "markdown": "# Touchstone\n\n**Provenance and portability for machine-written knowledge.**\n\nAn agent reads your source material and compiles a knowledge base where every claim cites what\nit came from, and the claims a human has actually checked are cryptographically signed.\n\nBuilt on [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)\nv0.2 — Google Cloud's open spec for knowledge as a directory of markdown concepts with YAML\nfrontmatter.\n\n## The problem\n\nOnce an LLM writes most of your knowledge base, two questions decide whether it is worth\nanything, and most tools answer neither:\n\n- **Which parts can you rely on?** Generated pages read exactly like verified ones. Without a\n  trust signal that cannot be forged, a knowledge base is a pile of plausible text.\n- **Can you leave with it?** Hosted tools export lossily by design. A corpus you cannot take\n  with you is not yours.\n\nTouchstone answers both by making them properties of the format rather than features of the\napp: raw bytes on disk are the truth, provenance is signed and travels with the bundle, and\neverything else — index, search, graph — is derived and disposable.\n\n## How it works\n\n```\nraw/         source documents, immutable, never parsed on the way in\n  ↓          an agent reads them and writes concepts that CITE them\nconcepts     markdown + YAML frontmatter, one file per idea, path is identity\n  ↓          a human signs the ones they have actually checked\nattest/      signatures over content digests, travelling with the bundle\n```\n\nEverything above the bundle is derived. Delete the index and every generated `index.md`,\nre-run `touchstone index`, and the result is byte-identical.\n\n## Install\n\n```bash\ncargo install --git https://github.com/gaberger/touchstone touchstone-cli\n```\n\nOr a prebuilt binary from [Releases](https://github.com/gaberger/touchstone/releases) — each\nships with a `.sha256` and is only cut after the conformance suite passes on that platform.\n\n## Use it\n\n```bash\ntouchstone --bundle ~/brain init\ntouchstone --bundle ~/brain ingest ~/Documents/notes    # recursive, deduplicated\ntouchstone --bundle ~/brain watch &                     # index stays current\n```\n\nCapture a thought — no editor, no title needed, 0.01s:\n\n```console\n$ touchstone --bundle ~/brain capture \"Q4 was never restated. Only Q1 got the corrected basis.\"\nnotes/q4-was-never-restated.md\n```\n\nAsk a question months later, in the words you actually have:\n\n```console\n$ touchstone --bundle ~/brain search \"why don't the quarterly figures agree\"\n* decisions/margin-restatement-is-incomplete.md\n    Margin restatement is incomplete  [Decision]\n    Only Q1 was corrected; Q4 still uses the old basis.\n\n* human-verified   ~ machine-generated\n```\n\nYou did not remember the title, the filename, or the word \"margin\". The `*` says a human\nsigned off on that one.\n\nAsk something grep cannot express at all — a *field*, not a word:\n\n```console\n$ touchstone --bundle ~/brain search \"margin\" --type Decision --status stable --trust human\n```\n\nThen ask where the claim came from:\n\n```console\n$ touchstone --bundle ~/brain show decisions/margin-restatement-is-incomplete.md --json\n{\n  \"path\": \"decisions/margin-restatement-is-incomplete.md\",\n  \"trust\": \"human\",\n  \"sources\": [\n    \"raw/interview-priya.txt\",\n    \"raw/email-thread.eml\"\n  ]\n}\n```\n\nAn interview and an email you ingested weeks ago. Both still in the bundle, byte-identical,\nand both travel with it when you leave.\n\nFinally: is that `human` tier worth anything?\n\n```console\n$ touchstone --bundle ~/brain verify\n0 of 1 human claims backed                      # a claim is just text until it is signed\n\n$ touchstone --bundle ~/brain attest decisions/margin-...md --as human:gary --key ~/.ssh/id_ed25519\n$ touchstone --bundle ~/brain verify\n1 of 1 human claims backed\n\n$ echo \"an edit nobody verified\" >> decisions/margin-...md\n$ touchstone --bundle ~/brain verify\nSTALE: decisions/margin-restatement-is-incomplete.md\n  signed, but the concept changed since -- the verified bytes are not these bytes\n```\n\nThe signature covers the content digest, not the path. Editing a signed concept invalidates its\nattestation instead of carrying it along.\n\n---\n\n**→ [How to run this as a business brain](docs/USING.md)** — what to ingest and what to\nignore, when an email becomes a concept, which types to be strict about, what to sign, and the\nanti-patterns that turn a knowledge base back into a folder of files.\n\n## For agents\n\n```bash\ntouchstone --bundle ~/brain mcp                        # stdio\ntouchstone --bundle ~/brain mcp --http 127.0.0.1:8765  # Streamable HTTP\n```\n\nThirteen tools at MCP revision **2026-07-28**, each with input *and* output schemas and\nannotations so a client knows which calls need a human in the loop. `touchstone_unprocessed`\nreturns the uncompiled sources *with their content*, so an agent gets the work and the material\nin one call.\n\n```json\n{\n  \"mcpServers\": {\n    \"touchstone\": {\n      \"command\": \"touchstone\",\n      \"args\": [\"--bundle\", \"/absolute/path/to/brain\", \"mcp\"]\n    }\n  }\n}\n```\n\n**No tool can write `verified`.** Signing needs a private key a human holds, and `attest` is\ndeliberately absent from the MCP surface — it is the one capability an agent must not have.\n\n## Commands\n\n| | |\n|---|---|\n| `init` | Create the bundle layout |\n| `capture <text>` | Record a thought in one command |\n| `ingest <path>...` | Copy sources into `raw/`, byte-exact, recursive, deduplicated |\n| `unprocessed` | Raw documents nothing cites yet — the work queue |\n| `index` | Rebuild the derived plane. Idempotent, incremental on content hash |\n| `watch` | Reindex continuously as files change |\n| `search <query>` | Structured prefilter → BM25 → one graph hop → trust rank |\n| `show <path>` | One concept's derived view; `--json` for parsed frontmatter |\n| `stats` | Counts by type, trust tier, status; links and broken links |\n| `lint` | Conformance floor, duplicate checks, uncited machine-written concepts |\n| `fmt [--check]` | Canonicalise frontmatter; refuses what it cannot reproduce |\n| `attest <path>` | Sign a concept's `verified` claim |\n| `verify` | Check every claim against the signed manifest |\n| `export <dir>` | Write everything back out — concepts, artifacts, sources, signatures |\n| `new <Type> <Title>` | Scaffold a conformant concept |\n| `mcp` | Serve the tool surface |\n\nFilters: `--type`, `--tag`, `--status`, `--trust`, `--limit`, `--no-expand`.\n\n## Design rules\n\n**Raw text is authoritative.** Frontmatter is parsed for querying, never treated as the truth.\n`export` writes raw bytes, so there is no serializer in the write path that could drop an\nunknown key — the failure mode is structurally impossible rather than merely tested for.\n\n**Everything touchstone generates is derived and disposable.** An `index.md` in a directory\nwith no concepts is authored knowledge, not generated, and is left alone.\n\n**The spec's tolerance is honoured, not narrowed.** Unknown types, unknown keys and broken\nlinks are all preserved and indexed. A broken link is knowledge about a gap.\n\n**Trust tiers are derived, never authored.** `verified[].by` starting with `human:` → trusted;\n`generated` present without it → machine; neither → unattributed. Search ranks on this.\n\n## How we prove it works\n\nCorrectness is a **conformance suite that drives the shipped binary as a black box** — it names\nno internal crate, so the same drills can gate a different implementation:\n\n```bash\nTOUCHSTONE_BIN=/path/to/other/impl cargo test -p touchstone-conformance\n```\n\n40 drills run against five bundles — an adversarial fixture plus four vendored third-party ones\nwritten by people who never saw this code:\n\n| | |\n|---|---|\n| Byte-exact round trip | CRLF, unicode paths, YAML anchors, block scalars, PNG/PDF/MP4 |\n| Deterministic rebuild | delete the derived plane; output is byte-identical |\n| Spec tolerance | unknown types and keys preserved, broken links recorded |\n| Signed provenance | unbacked, stale and forged claims each detected distinctly |\n| CLI/MCP parity | the two surfaces produce identical bytes for the same operation |\n| Scale | 50,000 concepts index in 11.85s; query in 0.11s |\n\nPlus 184 unit and integration tests, a layering check that makes an architecture violation a\ncompile error, and the whole gate on every push.\n\n**What is not proven, stated plainly:**\n\n- **Does it beat `rg` + Obsidian?** Weak evidence. On a real corpus with a fairly-ranked\n  baseline, touchstone answered 18 of 20 questions against the baseline's 11 — but the\n  questions were not written by a disinterested party. See `a10/`.\n- **Will anyone write into it unprompted?** Untested. Instrumented and waiting for three weeks\n  of real use. See `a3/`.\n- **Who do you trust?** `attest/allowed_signers` is the bundle's own assertion about its\n  signers, not a PKI. It makes tampering detectable, not identity certain.\n\n## Documents\n\n| | |\n|---|---|\n| [docs/USING.md](docs/USING.md) | How to run one as a business brain — what to ingest, what to write, what to sign |\n| [ARCHITECTURE.md](ARCHITECTURE.md) | The design as it is today |\n| [docs/adrs/](docs/adrs/) | Why each decision was made — append-only |\n| [PROTOTYPE.md](PROTOTYPE.md) | How to falsify it. Pre-registered kill criteria |\n| [FINDINGS.md](FINDINGS.md) | Experimental results, including the claims that turned out false |\n| [_sample/](_sample/) | A mixed-media corpus to try it against |\n\nMIT licensed.\n",
  "bytes": 9433,
  "sha": "048313082c1f03671c770f20a282bce35e6523d1b6562946b43a8af22f420aae",
  "repo_slug": "gaberger/touchstone",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_gaberger_touchstone_fixture_index_md_360adebd/readme"
}