KO - Knowledge Objects

Quick Start

1. Install the Claude Code Plugin

Use the /ko-setup skill in Claude Code to automatically configure the plugin. It will set up KO_DIR environment variable and register the plugin in your settings.

2. Create Your First KO

Tell Claude Code to save a decision, fact, or insight as a KO. It will use /ko-store to create a structured Knowledge Object with full YAML frontmatter.

3. Recall Knowledge

Use /ko-recall to search KOs by keyword, tag, type, or id. KO summaries are also auto-loaded at every session start.

KO Schema

Every Knowledge Object is a markdown file with YAML frontmatter following this schema:

Field	Values	Description
type	fact / decision / pattern / insight / skill	Classification of the knowledge
status	review / verified / disputed / archived	Quality control state
confidence	high / medium / low	How confident we are
source	conversation, references	Change log + structured citations (v0.8: dropped channel / agent / message_id)
scope	projects, domains, valid_from, valid_until	Where and when this applies
generalizability	level, transferable_to, context_dependent_parts	How broadly this KO can be reused
usage	retrieval_count, cited_count, helpful_count	Usage tracking statistics
related	ko-001, ko-002, ...	Links to related KOs

Body Content

The body is free-form markdown — no required structure, no mandatory sections. Write whatever fits the topic: a definition, a comparison table, a numbered procedure, code snippets, prose, or any mix.

tipOpen with a 1–2 sentence summary so the /space list card has something useful to show as a preview. After that, structure however helps the reader.

legacyOlder KOs use a ## Claim / ## Evidence / ## Context pattern. That convention is no longer required and not enforced by validation.

Writing Style

Writing style is tiered by type. fact and insight follow academic-paper conventions (numeric citations, structured references, paper-exportable via ko cite). Other types stay free-form.

Type	Style	Citations	First-person
fact	Academic	Required [N] + structured refs	Avoid (warns)
insight	Academic	Required [N] + structured refs	we OK; no I
pattern	Semi-formal	Recommended	OK
decision	Free-form	Optional	OK
skill	Free-form (procedural)	Optional	OK

Structured reference (fact / insight)

Each entry in meta.source.references is an object — not a bare string:

{
  "id": "polanyi1966",        // BibTeX cite key
  "type": "book",             // book|article|inproceedings|incollection|techreport|phdthesis|misc
  "authors": ["Polanyi, M."],
  "year": 1966,
  "title": "The Tacit Dimension",
  "venue": "University of Chicago Press",
  "url": "https://...",       // optional
  "doi": "10.xxxx/yyy"        // optional
}

Body conventions

Cite inline as [1], [2], [1,3-5]. Numbers index into references[] (1-based).
Do NOT hand-write the ## References section.It's auto-rendered by ko create / ko patch from meta.source.references[]. Manual edits get overwritten.
To change the bibliography, edit meta.source.references[] and push — the section regenerates.

Lint (`ko validate`)

Structured-reference rules trigger only when the body has [N] citations. A fact / insight without citations (internal spec, design note) can keep bare-string "see also" references.

[N] in body without references[N-1] → error (fact / insight)
references[i] is a bare string (when body has [N]) → error
references[i] missing id → warn
references[i] never cited → warn
First-person voice (we / I / 我们 / 我) outside quotes → warn (fact only, regardless of citations)

Paper export — `ko cite`

ko cite <id>                       # body with [N] → \cite{key} + BibTeX
ko cite <id> --format bibtex       # just BibTeX
ko cite <id> --format markdown     # body + rendered References block
ko cite <id> --out refs.bib        # write BibTeX to file

Output is paper-ready: paste the body into a .tex document; append the BibTeX to your .bib file.

Available Skills

Skills are user-invocable commands in Claude Code:

/ko-recall

Search and retrieve KOs by keyword, tag, type, or id. Supports bidirectional related KO traversal.

/ko-store

Create a new KO or update an existing one. Auto-fills source fields and generates sequential IDs.

/ko-verify

Update KO status (review → verified / disputed / archived). Records verifier and timestamp.

/ko-setup

One-time plugin setup. Configures KO_DIR and registers the plugin in settings.json.

Hooks

Hooks run automatically at different lifecycle points — no user action needed:

SessionStart

Auto-loads all KO summaries (id, title, type, status, confidence, tags) into Claude's context when a session begins.

UserPromptSubmit

Detects KO-related keywords in user messages and injects a hint about available skills. Silent when no KO keywords are present.

Stop

After Claude responds, automatically updates retrieval_count and last_used for any KOs referenced (ko-NNN pattern) in the conversation.

Setup & Config

KO Directory

Default: ~/Syncthing/ArchiveFiles/SecondBrain/KO

Configured via KO_DIR environment variable in ~/.claude/settings.json.

Plugin Registration

The plugin is registered as a local marketplace source in extraKnownMarketplaces and enabled via enabledPlugins in settings.json.

File Naming

KO files follow the format ko-NNN-slug.md, e.g. ko-009-koproduct-claude-code-plugin.md.

FAQ

How is KO different from mem9?

KO uses a structured five-attribute schema (type, status, confidence, source, scope) with a four-state quality lifecycle. mem9 stores unstructured key-value memories. KO is designed for verifiable, traceable team knowledge; mem9 is for lightweight agent memory.

Can multiple people use the same KO Space?

Currently V0.3 uses local filesystem storage with Syncthing sync. Multi-user collaboration with database backend is planned for V1.0 (see ko-010).

What happens if I reference a KO in conversation?

The Stop hook automatically detects ko-NNN patterns in the conversation and increments the retrieval_count and updates last_used in the referenced KO's frontmatter.

Enter KO Space →