No description
Find a file
Michał Kopeć db3d798e77 Template 2.4.0: merge dev — improvement memory (D-0023, schema 1.8)
Version made by merging dev into main, per D-0022. Contents: SIM features
1–6 from Google's Self-Improvement Memory paper — error book per recurring
problem with attempts (expected/observed/context) and aliases; decisions
with expected_outcome, outcome review, ## Tried; lesson context, upstream
lessons from linked/, ckb-init carry-over, merges; ckb-upgrade b5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 08:39:12 +01:00
.agents Improvement memory: attempts, expected outcomes, lesson context (D-0023) 2026-11-18 08:17:19 +01:00
.claude Remove legacy Claude config files 2026-07-29 22:21:17 +02:00
docs Template 2.4.0: merge dev — improvement memory (D-0023, schema 1.8) 2026-11-18 08:39:12 +01:00
libs Sync: local changes as of 2026-07-15T16:28:24+02:00 2026-07-15 16:28:38 +02:00
linked Sync: local changes as of 2026-07-15T15:57:36+02:00 2026-07-15 15:59:58 +02:00
outputs Template 1.22.0: agent-knowledge release 1 2026-11-02 19:25:02 +01:00
raw Sync: local changes as of 2026-10-29T13:50:12Z 2026-10-29 14:50:12 +01:00
templates Sync: local changes as of 2026-10-29T13:50:12Z 2026-10-29 14:50:12 +01:00
tests Improvement memory: attempts, expected outcomes, lesson context (D-0023) 2026-11-18 08:17:19 +01:00
tmp Sync: local changes as of 2026-07-15T16:28:24+02:00 2026-07-15 16:28:38 +02:00
user-skills Sync: local changes as of 2026-11-12T07:13:05Z 2026-11-12 08:13:05 +01:00
wiki Improvement memory: attempts, expected outcomes, lesson context (D-0023) 2026-11-18 08:17:19 +01:00
workload Sync: local changes as of 2026-11-01T20:31:36Z 2026-11-01 21:31:36 +01:00
.gitignore Template 1.13.0: conversation autosave switch with per-machine hook check 2026-10-16 09:38:35 +02:00
ABOUT.md Template 1.26.2: ABOUT.pl.md, the Polish pair of ABOUT.md 2026-11-10 09:35:57 +01:00
ABOUT.pl.md Template 1.26.2: ABOUT.pl.md, the Polish pair of ABOUT.md 2026-11-10 09:35:57 +01:00
AGENTS.md Improvement memory: attempts, expected outcomes, lesson context (D-0023) 2026-11-18 08:17:19 +01:00
ckb.yaml Template 1.28.1: 1.x maintenance channel, major-version guard (D-0019) 2026-11-11 13:47:37 +01:00
CLAUDE.md Remove legacy Claude config files 2026-07-29 22:21:17 +02:00
LICENSE Sync: local changes as of 2026-07-17T12:45:15Z 2026-07-17 14:45:15 +02:00
README.md Improvement memory: attempts, expected outcomes, lesson context (D-0023) 2026-11-18 08:17:19 +01:00
README.pl.md Improvement memory: attempts, expected outcomes, lesson context (D-0023) 2026-11-18 08:17:19 +01:00
VERSION Template 2.4.0: merge dev — improvement memory (D-0023, schema 1.8) 2026-11-18 08:39:12 +01:00

Cascade Knowledge Base

Read this in: English | Polski

Source repo (always the most up-to-date version): git.wierzbowa.cloud/michal/ckb

What this knowledge base holds: see ABOUT.md - its purpose, audience, scope, owners and sensitivity, written by whoever runs this KB. The rest of this README describes the Cascade KB tooling, which is the same in every KB.

A layered, agent-managed wiki where local content overlays read-only upstream sources. Built on Karpathy's LLM Wiki pattern with extensions for scaling, lifecycle management, and multi-agent support.

This document is a technical feature overview. For a task-oriented guide - how to create a wiki, add knowledge, keep it tidy, sync with others, and worked examples for every use case - see docs/MANUAL.md (Polski). New to it? Start with the one-page docs/QUICKSTART.md (Polski).

If this KB documents software you're building, the optional software module adds src/ repositories and spec-driven development - see docs/OPENSPEC.md (Polski).

To use the KB from Claude's web app or any other MCP client, the optional mcp module serves it over MCP: search and read, submissions to raw/inbox/, and undoing a misfiled one, with several KBs connected at once - see docs/MCP.md (Polski). To clip web pages, PDFs and video transcripts into raw/inbox/, the optional capture module saves each as a dated, untrusted-marked snapshot. To send a document to another KB, the optional share module uses a shared git repo with one mailbox per KB; the receiver takes it into raw/inbox/ and ingests it as usual. To write everything the KB sends out in your team's voice, the optional voice module rewrites kept answers, documents and reports from a voice profile kept as a wiki page, without touching facts, quotes or sources. To hand a document over as a Word file or a PDF, the optional convert module runs pandoc with a house style kept in templates/styles/, built from a few settings or from your company's Word template. Every module has its own README in both languages under .agents/modules/<name>/.

For the page schema in full, and for how both version numbers got where they are, see docs/CHANGELOG.md (Polski). Why the template is shaped the way it is - its own design decisions - is in docs/decisions/.

Release channels

The template repo keeps four release branches, plus dev, where work lands. They are not interchangeable:

Branch What it is Who should track it
main Stable - the released template Everyone, by default
test Release candidate - validated before merging to main Anyone helping validate a release, or needing a landed-but-unshipped fix
experimental Preview - work merged from dev early, may be broken or reverted People developing the template itself
1.x Maintenance - the 1.x line after 2.0: fixes only; the last line with PowerShell support KBs that need PowerShell, or can't move to 2.0 yet
dev Integration - where every change lands first; VERSION never changes here Nobody: not a channel (an upgrade from it finds nothing newer)

The version changes only when dev is merged into another branch, never on dev itself. Changes travel dev → experimental → test → main, dev → test → main, or dev → main; a version keeps its number as it moves along. What each number position means is unchanged: major for breaking changes, minor for features, patch for fixes. See D-0022.

Both ckb-init and ckb-upgrade default to main. To use another channel, say which: "initialize from the test branch", "check experimental for updates", "switch this KB back to the stable channel". The branch a KB tracks is recorded in ckb.yaml:

template:
  repo: https://git.wierzbowa.cloud/michal/ckb.git
  branch: main

A KB with no ckb.yaml (or no template: block) is treated as tracking main, as every KB predating this convention already did.


Directory Structure

├── ABOUT.md      # What this KB holds: purpose, audience, scope, owners - yours to write
├── ABOUT.pl.md   # The same in Polish - fill in the one in your KB's language
├── ckb.yaml      # Repo manifest: template branch tracked, installed modules, conversation settings, routines
├── docs/         # Manual, changelog, OpenSpec guide, and decisions/ — the template's own ADRs
├── tests/        # Template repo only: fixture KB + smoke test (tests/smoke.sh); not copied into KBs
├── libs/         # Read-only external sources — git-copy clones (gitignored) OR
│                 #   connector configs (source.yaml) with a self-contained generated index
├── linked/       # Read-only upstream KBs mounted as symlinks
├── outputs/      # Generated artifacts, exports, compiled files
│   └── documents/  # Documents prepared from templates/
├── raw/          # User-provided source material
│   └── inbox/    # Drop zone: unprocessed material
├── templates/    # Your document templates: headings plus a comment per section as the brief
├── tmp/          # Temporary files, caches (gitignored)
├── wiki/         # Local structured markdown wiki (agent-managed)
│   ├── index.md      # Routing table with "Use when" triggers + kb_schema_version
│   ├── overview.md   # What this KB covers — content, not schema
│   ├── log.md        # Root rollup change log
│   ├── error-book.md # Compilation errors & derived constraints
│   ├── query-gaps.md # Failed or missing-answer questions for future ingest
│   ├── projects/     # Optional local query scopes
│   ├── decisions/    # Numbered, append-only decision records + own index.md & log.md
│   ├── entities/     # Typed entity pages (people, projects, concepts) + own index.md
│   └── graph/        # Edge lists and relationship data + own index.md
└── workload/     # Session summaries & decisions
    └── YYYY-MM-DD_<author>_summary.md

Cascade Priority

When searching, layers are checked in order - first match wins:

wiki/        (highest)  ← agent writes here, always wins
linked/A/    (medium)   ← symlinked upstream KBs
linked/B/    (low)      ← symlinked upstream KBs
libs/A/      (lowest)   ← git-managed external KB copies, or a connector's own generated index

The agent never writes to linked/ or a git-copy libs/<name>/. To correct upstream content, write the right version in wiki/ - it takes precedence automatically. The one exception is a connector-backed libs/<name>/ (see "External Source Connectors & Indexing" below): the agent owns and maintains its generated index the same way it does wiki/.


Features

Every feature below is a skill under .agents/skills/. A skill loads into context only when invoked; AGENTS.md carries the routing and the non-negotiable rules, nothing more.

Inbox-Driven Workflow

Drop any raw material (notes, articles, links) into raw/inbox/ without organizing. On "Ingest" (or "Update the wiki"), the agent processes the inbox - extracts knowledge, files it into wiki/, and archives processed items to raw/ - then reminds you to review the result and run "sync changes" to push it to origin once you're happy with it. Skill: .agents/skills/ckb-ingest/SKILL.md.

Before writing, a script (dedup_inbox.py) reports inbox files already ingested: byte-identical or same-text copies of archived files, files whose digest a page already cites, links to URLs a page already cites, and duplicates within the inbox. The agent then checks in: per source, its reading, the pages it will touch and what it contradicts. Nothing is written until you answer. "Ingest in batch" skips the check-in. Text wrapped in <private>…</private> is never ingested.

For long conversations, meeting notes, transcripts, or chat exports, ingest uses a structured distillation rather than treating the whole file as one undifferentiated blob: searchable question, short summary, resolution or decision, systems/code references, people involved, and high-signal excerpts that deserve to stay findable on their own.

"High-signal" is an explicit test, not a judgment call, or every excerpt looks worth keeping and the page becomes a second copy of the transcript. An excerpt earns its own retrievable section only if it carries a term rare across the wiki (checked with rg -c - a distinguishing search handle, not a word already on twenty pages), runs to roughly 200 characters or more, and is corroborated by something later in the material agreeing with, acting on, or correcting it. Fail any one and the content still lands in the page, just inside the summary rather than as its own unit. Promoted excerpts carry their parent heading or thread question with them, so they read unambiguously alone.

Lazy-Loading Index with "Use When" Triggers

wiki/index.md is a routing table. Each entry has a Use when column listing trigger keywords. The agent reads the index first (stays in context), matches keywords against the task, and only loads matching pages. The index stays small; the pages it points at don't have to.

TLDR-First Query Layer

Every page carries a one-sentence tldr in frontmatter. When querying, the agent reads TLDRs first. If the TLDR already answers the question, the agent never loads the full body. Fallback chain: TLDR → body → raw source.

Local Project Scopes

For recurring teams, clients, systems, or initiatives, the wiki can keep plain Markdown scope pages under wiki/projects/. A scope page lists the wiki pages, entities, raw/archive sources, connector-backed libs, outputs, and graph areas to search first for that project. You get what a project workspace gives you in a larger retrieval system, but the scope stays local, transparent, and editable in any text editor.

Scopes only narrow the first pass. If the scoped search does not answer the question, the agent falls back to the full cascade.

Local Hybrid Retrieval

When index/TLDR routing is not enough, the agent can combine several local signals before answering:

  • exact text search with rg for error strings, commands, flags, filenames, hostnames, ticket IDs, and other literal tokens - including across raw/inbox/, so material dropped an hour ago and not yet ingested can still answer a question (and flags that an ingest is overdue)
  • semantic/entity matches from page titles, TLDRs, project scopes, and graph relationships
  • freshness and confidence metadata, so stale or weak pages are treated with care
  • context expansion around a matched section, so answers are grounded in the neighboring headings and paragraphs rather than a lone snippet
  • BM25 section search through SQLite FTS5 (standard library), each section indexed with its page title, heading path and tldr as context, so a candidate names the sections that matched and its token cost

Gathering and fusing those signals is mechanical, so it runs as a script - .agents/skills/ckb-retrieve/scripts/retrieve_candidates.py - the same way lint's detection does; the agent reads its ranked output and does the judgment (dedupe by claim, rerank against the literal question, source verification). Each signal produces its own ranked list, and the lists are then fused rather than resolved by picking a favourite: every candidate scores weight / (k + rank) summed across the lists it appears in, so a page ranked third by three signals beats one ranked first by a single signal. k is 10, deliberately smaller than the 60 rank fusion is usually quoted with - 60 is tuned for retrievers returning hundreds of candidates and flattens all scores into near-identical values against the dozen a local wiki produces. Literal-token queries up-weight the exact-match list, since no amount of title similarity should outrank a match on the exact string someone pasted.

Fused candidates are then deduplicated by claim - a wiki page, the raw/archive/ file it cites, and a connector page pointing back at it are three hits for one fact, not three sources - and reranked 0–10 on how well each answers the literal question rather than how well it matches the question's wording. Same agent, deliberate second pass, no separate model.

The result is normalized internally as an evidence packet: source path, matched claim, date/freshness, confidence/quality, relationship or scope hints, and which signals each candidate was fused from. No server, vector database, or dedicated client is required.

Answer Caveats

Metadata the wiki already tracks is stated in the answer itself, not just consulted while building it. When a page grounding an answer is past its freshness_window_days, carries low confidence/quality, rests on un-ingested raw/inbox/ material, or was checked against a cached connector index rather than a live re-fetch, the answer says so next to the claim it qualifies. Conflicts between two live pages are surfaced the same way even when neither carries superseded_by yet. The failure mode this closes is answering confidently from a stale page without passing that on.

Consolidation and Topic Summaries (on demand)

"Consolidate" writes a proposals-only report to outputs/reports/: topic clusters (and whether each wiki/topics/ page is missing or outdated), merge candidates, missing links, stale pages and old log entries. Nothing in the wiki changes until you approve an item. Approved topic pages summarise what the KB holds about one subject and list their member pages with digests, so lint flags a topic when a member changes. Skill: .agents/skills/ckb-consolidate/SKILL.md.

Profiles and Lessons

Each person can keep a profile in workload/profiles/ (role, how to work with them), printed into their own session-start brief and nobody else's. "Remember this" or "lesson: …" records a lesson: a personal one in the profile, a KB-wide one in wiki/lessons.md, which waits for a second person's review. Precedence is AGENTS.md, then a project's ## Rules, then the profile. Each lesson records the context it was learned in (agent/model, template version), so after a model or template change the agent rechecks it instead of treating it as settled. Lessons from KBs under linked/ appear in the brief as upstream, ranked below local ones, and a new KB can start with lessons carried from the one that created it. Skill: .agents/skills/ckb-profile/SKILL.md.

Kept Answers

An answer that took real work can be kept on request in outputs/answers/, with fingerprinted ## Sources and a ## Gaps section. Lint flags a kept answer whose sources have changed, and asking the same question again updates the kept answer rather than duplicating it. Filing an answer back into the wiki goes through a normal ingest, never a direct write. Private (<private>) passages are never quoted.

Expertise & Ownership Lookups

"Who knows about X" and "who owns X" are direct graph lookups rather than full-text guesses. Ingest records has_expertise_in edges when someone demonstrably answers questions or explains decisions on a topic, and owns edges for declared responsibility over a system, area, or decision - both from demonstrated evidence only, never inferred from meeting attendance or job title. Where no edge exists yet, retrieval falls back to authorship evidence and says which of the two grounded the answer, since an inferred expert is a weaker claim than a recorded one.

Decision Records

wiki/decisions/ holds one numbered page per decision (NNNN-slug.md): what was decided, decided_by whom, decided_on what date, why, the alternatives that lost, and what it affects. A status field (proposed/accepted/rejected/superseded/reversed) says whether it is actually in force, and an optional review_on date marks it for revisiting. An optional expected_outcome, written when the decision is made, says what it should change; at review the agent records what actually happened (outcome: met/partly/missed/unclear) in an appended ## Outcome, and a ## Tried section keeps what was built or tested and dropped on the way.

Decision pages are append-only. When the choice changes, a new decision supersedes the old one - supersedes/superseded_by are set on both sides, the old page's status becomes superseded or reversed, and its original context and rationale stay untouched. That is what makes "why is it like this?" answerable years later, and what turns "we use Postgres" into "we use Postgres, and before that MySQL, changed in September because of reporting". decided_by and affects also become graph edges, so "who decided X" and "what decisions touch Y" are direct lookups. The ckb-decide skill records decisions and answers questions about them; ckb-lint checks their structure (status vocabulary, required dates, two-sided supersession, unique numbers, overdue reviews, unrecorded outcomes).

Query Gaps

If the cascade cannot answer a question, the agent records or proposes a short entry in wiki/query-gaps.md: what was asked, where it looked, and the smallest source or page that would close the gap. Failed searches then become demand signals for the next ingest instead of disappearing into chat history.

Page Frontmatter Schema

Every wiki page uses YAML frontmatter. type is required; the rest are optional:

---
type: concept              # REQUIRED. Open string: person, project, concept, library, decision, playbook, ...
resource: https://...      # Canonical URI to the authoritative external source this page describes
tldr: One-sentence summary optimised for LLM reading
confidence: 0.0–1.0      # Source corroboration score
quality: 0.0–1.0          # Self-evaluation (below 0.7 → flagged)
supersedes: path/to/old.md
superseded_by: path/to/new.md
last_updated: YYYY-MM-DD
freshness_window_days: 90 # Days before considered stale
retention: high|medium|low
source_fingerprint: sha256:3f9a2c1e   # digest of the source this page was built from
source_checked: YYYY-MM-DD            # when that digest was last verified
review: draft|reviewed|needs_update   # with reviewed_by / reviewed_on (1.6)
tags: retries, billing                # only tags listed in wiki/tags.md (1.6)
---
  • type - required; unregistered string, new values always valid, readers tolerate unrecognized ones
  • resource - optional pointer to the live/authoritative source, kept separate from the wiki's own commentary
  • confidence - set on write, decays with time, reinforced by new sources
  • quality - self-scored on write, pages below 0.7 flagged for review
  • supersedes / superseded_by - when new info replaces old, link them
  • freshness_window_days - pages older than this get flagged during lint
  • retention - low pages are archived after 2× freshness window
  • source_fingerprint / source_checked - a digest of the material the page was synthesized from, plus when it was last confirmed. A freshness window is a guess that a source might have moved; a fingerprint is a fact about whether it did, and lint checks it mechanically.
  • review / reviewed_by / reviewed_on - whether a person has checked the page: ingest writes draft, a person's "mark X as reviewed" sets reviewed, and a later change to what the page claims sets needs_update
  • tags - a flat list checked against the KB's own vocabulary in wiki/tags.md; retrieval can filter on it

Reserved body sections

Three ## headings mean something specific everywhere in the KB:

Section What it holds
## Sources one bullet per source, each with a fingerprint
## Crux verbatim quotes from those sources - evidence, never paraphrase
## Notes human-authored and protected: no skill rewrites it, ever
## Rules on project scope pages only: the team's rules for that project, protected like ## Notes

Where two sources disagree and nobody has decided which is right, ingest writes a > CONTRADICTION: … marker into the page instead of picking a winner; lint lists it until a person settles it.

## Crux is what lets a question be answered from the page instead of from the archive: a summary can drift silently, a quote either still matches its source or it doesn't. ## Notes is the inverse guarantee - on pages the agent regenerates (connector indexes, code maps), it is the one place an annotation survives the next rebuild.

wiki/index.md alone also carries kb_schema_version (currently "1.8"), declaring which revision of this schema the wiki was authored against - bump minor for additive optional fields, major for breaking changes.

Entity Extraction & Knowledge Graph

During ingest, the agent extracts typed entities (people, projects, libraries, concepts, systems) and stores them as pages in wiki/entities/. Typed relationships are recorded in wiki/graph/edges.json, using a closed vocabulary where each verb is defined by the question it answers (see wiki/graph/index.md) - structural ones (part_of, uses, depends_on, produces, configures, validates, implements, caused, contradicts, supersedes) plus people-to-topic ones (has_expertise_in, owns). Queries can walk the graph to discover connected pages (e.g. "what depends on Redis?") or to answer "who knows about X" directly.

Recursive Index & Log Convention

Any wiki/ subdirectory that groups multiple pages (entities/, graph/, future topic folders) keeps its own index.md - a plain link list, no frontmatter - so subdirectory navigation stays lazy instead of requiring a full scan. A subdirectory can also keep its own log.md once it has enough independent history; wiki/log.md stays the root-level rollup and never duplicates a change a subdirectory log already recorded - it carries a one-line POINTER entry instead. wiki/decisions/log.md is the one subdirectory log the base scaffold ships with, and Rule B in AGENTS.md names it as the exception.

External Source Connectors & Indexing (on demand)

A libs/<name>/ folder supports a second population mode alongside the existing git-copy one: a small user-authored libs/<name>/source.yaml declaring a live external source - a SharePoint folder, a Google Drive folder, a plain URL, or another connector - that you don't want to fully mirror locally:

connector: sharepoint
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
description: "Finance team's shared reports folder"
refresh_interval_days: 7   # optional, defaults to 30

refresh_interval_days tunes cadence per source - a folder that churns daily deserves a shorter window than a quarterly archive that barely moves - and sets the freshness_window_days stamped on that source's generated pages. Both "index external sources" and "Lint" report a source that's overdue against it, and say by how much, so a read-only user knows which admin to chase rather than quietly trusting a copy three weeks past due.

Say "index external sources" and the agent walks it, resolving connector to whatever live tool is available that session (a connected Microsoft 365/Google Drive MCP tool, or WebFetch for a plain URL), and builds a self-contained generated index inside that same libs/<name>/ - index.md/entities//graph//log.md, mirroring wiki/'s own shape via the Recursive Index & Log Convention above, but scoped entirely to that one connector. The index is not blended into the main wiki/entities//wiki/graph/edges.json - it stays separated at the libs/ cascade layer, the same way a git-cloned KB's own files already are. source.yaml itself stays user-only, never written by the agent.

Two refinements on top of that:

  • Shared, pre-built indexes. source.yaml can add an optional index: block declaring where the already-built index lives - a git repo, or a shared resource such as a network path or another connector-reachable location:
    index:
      store: git   # git | shared
      location: "https://github.com/org/finance-index-cache.git"
      ref: main    # optional — branch, tag, or subpath hint within that store
    
    Every run checks that location: if it already has an index, fetch it. Most people read what's already there instead of building it themselves. If it doesn't yet, that's the normal first-time state, not an error: the next run by a user with write access creates and publishes it there, with no separate "initialize" step.
  • Read vs. write, per user, per source. Whether this user can rebuild an index (versus only read a fetched/published one) is a separate, local, gitignored libs/<name>/source.local.yaml - read-only by default. Setting access: write there opts a given machine/user in as that source's admin, so a team can designate one or two people to maintain a source while everyone else reads the result - no redundant rebuilding, no need for every user to have their own connector authorization.

Skill: .agents/skills/ckb-index-external/SKILL.md.

Every cross-reference uses both [[Wikilinks]] (Obsidian-compatible) and standard [markdown](path.md) links. Works in Obsidian graph view, GitHub rendering, and CLI tools. Upstream references use full relative paths: linked/<name>/... or libs/<name>/.... Intra-wiki references prefer project-root-absolute paths (/wiki/entities/foo.md) over relative ones, so links survive later file moves.

Self-Healing Lint

Periodically (or on demand), the agent health-checks the wiki:

  • Conformance - flags any page missing parseable frontmatter or a type field
  • Freshness - flags pages past their freshness_window_days
  • Confidence decay - reduces confidence on unreinforced pages
  • Retention sweep - archives retention: low pages past 2× window
  • Supersession detection - finds contradictions, links old→new
  • Orphan detection - finds pages with no inbound links
  • Graph consistency - verifies all edges point to existing entities
  • Index/log consistency - verifies every subdirectory has an index.md and no change is double-logged
  • Source fingerprints - recomputes each cited source's digest and flags pages whose evidence has actually changed, not merely aged
  • Crux verbatimness - flags a quoted excerpt that no longer appears in the source it cites
  • Connector cadence - flags a connector-backed source whose generated index is overdue against its refresh_interval_days, and by how much
  • Secrets and private spans - flags credential shapes in committed text and <private> passages that reached wiki/, masked, never auto-fixed; harmless matches go in a line-hash .secrets-allow
  • Kept answers - flags answers in outputs/answers/ whose sources changed
  • Context budget - estimates the always-loaded layer (AGENTS.md plus skill descriptions) and flags it above budget.always_loaded_tokens in ckb.yaml
  • Error Book - records systemic issues with root cause and fix

Auto-fixes what it can (broken links, missing backlinks, stale flags), and reminds you to review the result and run "sync changes" to push it to origin once you're happy with it. Skill: .agents/skills/ckb-lint/SKILL.md.

Conflict Resolution (Supersession)

When new information contradicts an existing page, the agent adds supersedes / superseded_by links. The old page stays, marked stale. Version control for knowledge as well as files.

Quality Scoring

Every page gets a quality score (0.0–1.0) on write, based on structure, source citations, and consistency with the rest of the wiki. Pages below 0.7 are flagged for review or rewritten in the next lint pass.

Error Book

Systematic errors (orphan links, formatting issues, cross-page contradictions) are recorded in wiki/error-book.md, one entry per recurring problem. Each entry names the suspected root cause and keeps every fix tried against it: what changed, what it was expected to stop (written before the result was known), what later lint runs actually saw, and the model and template version it ran under. Fixes that did not hold stay on the record, so the same fix is not tried again blind. Two-layer repair:

  • Layer 1 - deterministic auto-fix for structural issues
  • Layer 2 - agent reasoning pass for semantic/cross-page issues

Session Conventions

These are rules the agent follows from AGENTS.md, not hooks wired into the harness - nothing in .claude/ runs on its own. If you want any of them enforced mechanically, that is a Claude Code hook or a scheduled agent you add yourself.

  • Session start → pick a title for the conversation from the first message and state it in one line (unless conversations.announce_title: false); one call to session_start.py stores it and prints the git status, the one-line lint_report.py --quick result, due routines and the last block of the latest workload summary; suggest ckb-sync-changes or ckb-lint only when either reports something; run due routines after the first request; when conversation autosave is on, also check this machine has the gitignored Stop hook in .claude/settings.local.json and ask before installing it. The brief also lists open threads: unticked - [ ] items under ### Open threads in workload notes
  • Session-start hook (opt-in, Claude Code) → with session.start_hook: true, a per-machine SessionStart hook injects the same brief before the first message and again after every compaction; the agent asks before installing it
  • Session end → append to workload/; repeat the unsynchronized-change check; after a session that did real work, ask once whether to save the conversation (ckb-add-conversation) - saved only on a yes, or without asking when conversations.autosave: true is set in ckb.yaml
  • Every turn that touches the KB → a note in workload/ (Rule D)
  • Wrong or misfiled source → ckb-retract removes it and exactly what it contributed (pages, claims, edges), after showing the plan; requests queued in raw/retractions/ (e.g. from the MCP server) are flagged at ingest
  • Unanswerable question → a wiki/query-gaps.md entry, the one write ckb-retrieve owns; answers are never filed back as pages automatically
  • Lint on demand or by routine → "Lint" runs the full check; "lint every week" makes it a routine in ckb.yaml that fires at the first session start after the period has elapsed (ckb-routine)

Demand-Driven Context (DDC)

The wiki grows from real agent failures, not upfront curation:

  1. Agent can't answer → identifies missing knowledge
  2. Proposes minimal entity/page to fill the gap
  3. User approves or provides source material
  4. Next ingest incorporates it

Session Summaries

After every conversational action, the agent appends to workload/YYYY-MM-DD_<author>_summary.md, one file per person per day, named and stamped with the git identity the session runs under. That gives continuity between sessions, a browsable history of how the KB evolved and, in a shared repo, a record of who did what without merge conflicts in workload/. The same identity goes on every wiki/log.md entry's **Author:** line. The agent reads the latest summary on session start, whoever wrote it, to pick up where things were left.

Change Log

Every wiki modification is immediately logged in exactly one log, in reverse chronological order: wiki/decisions/log.md for anything under wiki/decisions/, wiki/log.md for everything else, with a one-line POINTER in the root log when the decisions log absorbs a change. Lint flags a change recorded in both.

OKF Export (on demand)

The wiki can be exported as an Open Knowledge Format v0.1-conformant bundle at outputs/okf/, consumable by any generic OKF tool (e.g. Google's reference graph visualizer) without disturbing the richer internal schema (confidence/quality/retention/supersedes/dual-linking) that OKF doesn't natively understand. A deterministic Python script (scripts/export_okf.py) does the whole transform - frontmatter remapping, link rewriting, index and log regeneration, and an OKF conformance pass over its own output - so the export is reproducible rather than re-reasoned page by page; the agent runs it and relays the report. outputs/okf/ is gitignored - it's a fully-regenerated build artifact, so each machine/tool regenerates it on demand rather than carrying it in git history. Skill: .agents/skills/ckb-export-okf/SKILL.md.

Starlight Export (on demand)

The wiki can also be exported into an Astro + Starlight-consumable form at outputs/starlight/, producing a human-readable documentation website - unlike the OKF export, which targets machine/tool consumption. A deterministic Python script (scripts/export_starlight.py) handles frontmatter remapping, dual-link collapsing, wikilink resolution, asset copying, and sidebar generation; the agent only asks the two setup questions (export scope: full runnable scaffold vs. content-only; whether to include the log/error-book meta pages) and relays the script's report. Skill: .agents/skills/ckb-export-starlight/SKILL.md. Like outputs/okf/, outputs/starlight/ is gitignored as a regenerated build artifact.

Decision Log (on demand)

Say "record a decision: ..." (or just "we decided ...") to file a numbered decision record; ask "what did we decide about X", "who decided that", "which decisions are still proposed", or "what superseded decision 3" to get it back with the who, when, and status attached. Recording gathers the missing fields in a single round rather than an interview, wires the supersession links in both directions, adds decided_by/affects graph edges, and logs to wiki/decisions/log.md. See .agents/skills/ckb-decide/SKILL.md.

Guided Onboarding Tours (on demand)

Ask "onboard me on X" (or "where do I start with X", "mini tour of X") to get a short, read-only guided reading order: an overview paragraph plus an ordered list of wiki pages to read, built by walking the knowledge graph outward from the best-matching page (foundations first, then the topic itself, then what builds on it). Never writes to wiki/. See .agents/skills/ckb-onboard-me/SKILL.md.

Project Summary (on demand)

Ask for "a project summary" (or "where do things stand", "catch me up on the project") to regenerate PROJECT-OVERVIEW.md at the repo root - a one-to-two-page snapshot (overview, project state, actions & status, risks, assumptions) synthesized entirely from the current wiki/ contents and its knowledge graph. Always overwritten in full on re-run, never hand-appended to. See .agents/skills/ckb-project-summary/SKILL.md.

Documents from Templates (on demand)

Keep the documents you write often as templates in templates/: a Markdown file whose headings set the shape and whose HTML comments brief the agent on each section - ask the user, read this wiki page, keep it to three sentences. "Prepare a new document using template status-report" reads the template, asks its questions in one go, pulls the rest from the wiki and writes the result to outputs/documents/, with frontmatter naming the template and the pages used. Gaps become TODO: lines, not guesses. One example ships, templates/status-report.md; templates/README.md has the format. See .agents/skills/ckb-document/SKILL.md.

Git Sync (on demand)

On demand, the agent reconciles this repo's git history with its origin remote: it commits local changes, pulls and merges remote ones, shows you any conflicts file by file to resolve, then pushes the result automatically. Before staging, it scans what is about to be committed for secrets and stops on a hit. Say "sync changes" to trigger it. It has nothing to do with "Ingest", which turns raw/inbox/ into wiki/ pages and never touches git. "Sync" on its own always means git. Skill: .agents/skills/ckb-sync-changes/SKILL.md.

Saved Conversations (on demand)

Say "save this conversation" and the session's transcript is copied into raw/saved-conversations/<YYYY-MM-DD>/ - the JSONL Claude Code keeps, plus a readable .md rendering - and listed in that folder's index.md. Saved conversations stay outside retrieval: questions are still answered from the wiki alone. You can ask about the conversations themselves ("did we discuss X", "what did I tell you about Y") and get the exact exchange quoted back. To bring one into the wiki, copy its .md into raw/inbox/ and say "Ingest". Say "save conversations automatically" to flip conversations.autosave in ckb.yaml, after which every session is saved at its end without a question. Every session is titled by the agent from its first message; the first reply states the title, which names the saved transcript, and "stop telling me the title" silences that line. Skill: .agents/skills/ckb-add-conversation/SKILL.md.

Quiz Mode (on demand)

Ask to be quizzed on the wiki ("quiz me on X", "test my knowledge") for a one-off, scored knowledge check: the agent reads the relevant pages, generates open or multiple-choice questions grounded in specific wiki facts, runs them one at a time with immediate feedback and a running score, and closes with a verdict. Stateless - nothing is saved between runs. See .agents/skills/ckb-quiz/SKILL.md.

Guided Teaching Curriculum (on demand)

Ask to be taught the wiki ("teach me the wiki", "teach me about X", "run a teaching session") for a stateful course rather than a one-off quiz. First call plans it: scopes the material (optionally supplementing thin spots from the web, clearly marked as non-authoritative), asks whether it should be one session or a spaced series (duration, frequency, optional calendar .ics reminders), chunks the content into session-sized portions - preferring an extra session over cramming - and saves the accepted plan and a progress tracker to outputs/teaching/<topic>/. Later calls compare plan against progress, teach the next portion using a different technique each time (Socratic questioning, analogies, worked examples, teach-back, mnemonics, ...), spot-check retention, and re-teach weak spots before advancing. Never writes to wiki/. See .agents/skills/ckb-teach-me/SKILL.md.

Feynman Explanations (on demand)

Ask "Feynman me on X" (or "explain X to me properly", "what am I fuzzy on?") to have one wiki page explained in words a twelve-year-old owns, each block linked to the section it came from, and then every place the explanation went thin named and sorted: a gap in the page, a gap in its sources, or a gap in the explainer. The agent never fills a gap from its own knowledge. It then asks you to explain one piece back and goes one level deeper. With no concept named, it offers draft, single-source or stale pages. The session is saved to outputs/teaching/feynman/; a source gap goes into wiki/query-gaps.md only on your yes. See .agents/skills/ckb-feynman/SKILL.md.


Quick Start

  1. Optional: install Python 3.8+. Eight skills run a stdlib-only Python script; without it the session-start check falls back to a bash script (Git Bash on Windows), lint and retrieval run in a slower manual mode, and the exporters are unavailable. Per-OS steps: docs/MANUAL.md → Prerequisites.

  2. Mount upstream KBs:

    ln -s /path/to/other-kb ./linked/my-upstream
    git clone https://github.com/org/external-kb ./libs/external-kb
    

    Or, for a live source you don't want to fully mirror, drop a libs/<name>/source.yaml instead (see "External Source Connectors & Indexing" above) and say "index external sources."

  3. Drop raw material into raw/inbox/ (notes, links, articles).

  4. Tell an agent to "Ingest" - it processes the inbox, consults the cascade, extracts entities, and writes structured markdown into wiki/.

  5. Ask questions - the agent uses the index for routing, TLDRs for quick answers, and the graph for relationship discovery.

  6. Periodically ask to "Lint" - the agent health-checks everything, auto-fixes what it can, and reports issues.


Agent Instruction Files

File Purpose
AGENTS.md Full instruction for any AI coding agent
CLAUDE.md Symlink to AGENTS.md, auto-detected by Claude Code

Skills live in one shared location, .agents/skills/, so any agent tooling that reads that convention picks them up. .claude/skills is a symlink to .agents/skills - Claude Code sees the same skill set without a second copy to keep in sync.


Tips

  • Upstream KBs (linked/ and git-copy libs/) are never modified by agents. A connector-backed libs/<name>/ (one with a source.yaml) is the one exception - the agent owns and maintains its generated index, but only for a user who's opted themselves into access: write locally (see the next point); everyone else's copy stays read-only.
  • To correct upstream content, write the correct version in wiki/ - it wins.
  • Use raw/inbox/ for anything unprocessed; the agent clears it on ingest.
  • The wiki/index.md routing table is the most important file - keep it current.
  • Confidence, quality, and freshness let you trust the right content and flag the rest for review.
  • tmp/ is gitignored. So is most of libs/, with one split: a git-copy libs/<name>/ stays gitignored, while a connector-backed one has its source.yaml and generated index.md/entities//graph//log.md tracked. That index is synthesized knowledge worth sharing via "sync changes", not a build artifact. libs/<name>/source.local.yaml is the exception inside the exception: personal machine state, never synced.
  • outputs/ is tracked, but outputs/okf/ and outputs/starlight/ are not. Each is reproducible from wiki/ on demand, so there is nothing to reconcile by carrying it in history. Commit hand-maintained artifacts under outputs/ as normal.
  • outputs/teaching/ is gitignored too. Learning plans, session progress and Feynman sessions are personal, not shared KB content.

Version & License

Current template version: VERSION. Licensed under the Apache License 2.0.