ranbot-ai/compile-knowledge

Compile Knowledge

Overview

Durable knowledge is worth keeping as many small, interlinked markdown files compiled over time and surfaced through an index — not as one giant doc, a chat log, or a one-off notes.md that rots. This skill makes compiling consistent, so what an agent learns in one session is retrievable in the next one instead of being re-derived from scratch.

The shape is deliberately boring: one fact per file, a one-line description that recall matches against, [[slug]] links between related files, and a single index line per entry. The hard part is not the format — it is the discipline of writing only what is durable, and of updating an existing file instead of creating a near-duplicate.

When to Use This Skill

• Use when you have just produced research, competitive intel, a digest, or an investigation result, and are about to close the task — compile before you close.
• Use when you learn a non-obvious fact the hard way (a tool that fails silently, a measurement that contradicts the docs, a constraint nobody wrote down).
• Use when the user says "save this", "write this to the wiki", "update the memory", "log this finding", "structure this knowledge", or "follow the karpathy method".
• Do not use it for routine work. A deploy, a restart, or a one-line fix usually produces nothing durable, and filler pollutes recall.

How It Works

Step 1: Pick the store

• Agent memory — the per-agent folder your harness already loads (memory/ with an index file such as MEMORY.md). This is the default and, for a solo agent, usually the only store you need.
• Shared wiki — a wiki/ folder with wiki/index.md, for knowledge the whole team would otherwise re-derive. Skip it entirely if you work alone; do not manufacture team ceremony.

Rule of thumb: "only I act on this" goes to memory, "anyone on my team might need this" goes to the wiki. Cross-link the two with [[slug]] rather than copying the fact into both.

Step 2: Pass the hygiene gate

Compile only a fact that is durable and non-obvious. Skip it if it is derivable from the repository, the git history, or the existing docs; if it is true only for this one conversation; or if an existing file already covers it — in that last case update that file.

Step 3: Search before you write

Grep the store and skim the index for the topic. A near-duplicate is worse than no entry, because recall then has two answers and no way to choose between them.

Step 4: Write one atomic file

One fact per file. Two unrelated facts are two files. Name it as a kebab-case slug — the slug is the link target, so it has to be guessable by the next reader. Frontmatter carries name (equal to the slug), a one-line description specific enough to be matched during recall, and a type or category. In the body, state the fact plainly and link related entries with [[slug]] liberally; a link to a file that does not exist yet is a fine TODO marker, not an error.

Step 5: Add exactly one index line

Use one line in the form - Title → slug.md — hook, under ~200 characters. Detail lives in the file; an index line that restates the file defeats the point of having an index. Create the index if it is missing, or the store is undiscoverable.

Step 6: Age the fact instead of letting it rot

Facts expire. When one is time-sensitive or replaces an older one, say so in the frontmatter so recall can demote it rather than serving stale truth:

• valid_to: YYYY-MM-DD — the date the fact needs a recheck.
• supersedes: <slug> — the older fact this replaces. Prefer this over editing in place when the old value is still worth seeing; edit in place when it is not.
• confidence: high|medium|low — so a hunch never outranks a measurement.
• provenance: "<source>" — where the fact came from, distinct from who wrote the note.

All four are optional and portable; omitting them changes nothing.

Examples

Example 1: A measured, non-obvious fact goes to memory

---
name: reference_search_api_counts_prs_as_issues
description: "GitHub's /search/issues endpoint counts pull requests in total_count, so a zero there proves neither issues nor PRs exist — but a non-zero one does not tell you which."
confidence: high
provenance: "measured 2026-08-16 while dupe-checking four upstream repos"
---

`total_count` from `/search/issues?q=<term>+repo:<owner>/<name>` is the sum of issues and
pull requests. For a "has anyone submitted this yet?" check that is exactly what you want,
and the zero is a real absence. To separate the two, add `type:pr` or `type:issue`.

Related: [[reference_gh_api_ref_serves_default_branch]].

Then one line in the index:

- Search API counts PRs as issues → reference_search_api_counts_prs_as_issues.md — a zero is a real absence, a non-zero is ambiguous

Example 2: Nothing durable came out of the task

Task: bump the service's log level to debug and restart it.