Knowledge

Manage the PAI Knowledge Archive — a curated, typed graph of notes across four entity domains: People, Companies, Ideas, and Research. Operations cover search, add, harvest, develop, ingest, contradiction-finding, graph traversal, compressed retrieval, and mining recent conversations for memory candidates. Every note ships with typed related: cross-links, so the archive is a connected graph, not a pile of files.

Notes you save in isolation are notes you never find again. A flat folder of facts has no way to tell you that two notes contradict each other, that a new source updates an old claim, or that an idea connects to a person and a company you wrote up months ago. Knowledge dies when it can't be retrieved or related. This archive forces every note into a typed schema with mandatory cross-links and ripples updates through related notes on ingest, so the connections are built in at write time instead of being reconstructed by hand later.

Manage the PAI Knowledge Archive at ~/.claude/PAI/MEMORY/KNOWLEDGE/. Each operation routes through a subcommand below; notes follow the archive schema and ship with typed cross-links.

Archive schema: ~/.claude/PAI/MEMORY/KNOWLEDGE/_schema.md

If $ARGUMENTS doesn't match a subcommand, treat it as a search query.

Run the harvester status command and display results:

bun ~/.claude/PAI/TOOLS/KnowledgeHarvester.ts status

Also show:

• Quick summary of domains with note counts
• Any orphan wikilinks
• Any stale seedlings
• Time since last harvest

Present in NATIVE mode.

Search the Knowledge Archive for notes matching $ARGUMENTS.

Step 1 — Lexical search:

rg -i "$ARGUMENTS" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l

Step 2 — Frontmatter search (tags and titles):

rg -i "title:.*$ARGUMENTS|tags:.*$ARGUMENTS" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l

Step 3 — Wikilink search:

rg "\[\[.*$ARGUMENTS.*\]\]" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l

Deduplicate results across all three. For each match, read the first 5 lines of frontmatter to show title, domain, status, tags.

Present results as a table:

| Note | Domain | Status | Tags | Relevance |

If no results found, say so and suggest checking the full MEMORY/ system or running a harvest.

Create a new note manually in the specified entity type.

1. Validate type is one of: People, Companies, Ideas, Research
2. Ask for a title (or use remaining args after type)
3. Generate kebab-case filename from title
4. MANDATORY: Find 2-3 related notes first. Before writing the new note, grep existing Knowledge for related entities by topic/tags/name. This becomes the related: frontmatter array. No Knowledge note ships without typed links. See Canonical Linking Requirement below.
5. Create the note with proper frontmatter from _schema.md — schemas require: title, type, tags (min 1), created, updated, quality (0-10), plus type-specific body sections.
6. Write the file to KNOWLEDGE/<Type>/<kebab-case-title>.md — slug max 60 chars
7. Verify every slug in related: exists in the archive before saving
8. Regenerate the type's MOC:

bun ~/.claude/PAI/TOOLS/KnowledgeHarvester.ts index

Topic is a tag, not a type. A security insight is an Idea with a security tag. A security company is a Company with a security tag. The entity type determines the schema; the tag determines the topic.

Every new Knowledge note must ship with typed cross-links. This is not optional. The architecture is defined in MEMORY/KNOWLEDGE/Ideas/pai-knowledge-linking-architecture.md (quality 9) and the schema in _schema.md.

Every write must include:

1. related: frontmatter array — 2-4 typed entries linking to other Knowledge entries (any domain: People, Companies, Ideas, Research)
2. Body wikilinks — 1-3 [[slug]] references woven into the prose where natural (Implications, Evidence, or Context sections)

8 relationship types (pick the most accurate, prefer specific over generic):

Frontmatter format:

related:
  - slug: other-note-slug
    type: extends
  - slug: another-note-slug
    type: supports

How to find related notes before writing:

# By topic/keyword
rg -l "TOPIC" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md

# By tag overlap
rg "^tags:.*TAG" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l

# For People/Companies — grep by name
rg -l "Person Name" ~/.claude/PAI/MEMORY/KNOWLEDGE/

Enforcement:

• Writes that skip related: are incomplete and must be fixed before the skill/workflow returns success
• The ingest workflow runs this as part of the ripple pass
• The Algorithm LEARN phase includes this in its knowledge capture step
• All agents writing Knowledge entries must follow this rule — it is part of the schema, not an optional enhancement

Run the KnowledgeHarvester to pull new knowledge from all PAI sources:

bun ~/.claude/PAI/TOOLS/KnowledgeHarvester.ts harvest

Display results. If nothing was harvested, explain that sources are already up to date.

Optionally accept --source filter: /knowledge harvest work or /knowledge harvest memory.

The weekly gardening workflow. Surface seedling notes that are ready for enrichment.

Step 1 — Find seedlings:

rg "^status: seedling" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l

Step 2 — For each seedling:

• Read the note
• Read related notes (follow wikilinks, search for same tags)
• Check if newer WORK/ ISAs or auto-memory entries have relevant context
• Enrich the note: add context, suggest wikilinks, flesh out content

Step 3 — Present the diff to the user for approval.

Step 4 — If approved:

• Write the updated note
• Promote status from seedling to budding (or evergreen if comprehensive)
• Update the updated date
• Regenerate affected MOCs

If no seedlings exist, report archive is clean.

Ingest a source into the Knowledge Archive. This is the key Karpathy-inspired upgrade: reading a source doesn't just create one note — it ripples updates through existing related notes.

If no argument provided: Show usage: /knowledge ingest <url-or-file-path>

Step 1 — Fetch the source

• URL: Use WebFetch to retrieve and read the content. If WebFetch fails, try curl -sL via Bash.
• File path: Use Read tool to read the local file.

Summarize the source in 2-3 sentences. Identify key entities, claims, and insights.

Step 2 — Classify and create primary note

Determine entity type (People, Companies, Ideas, or Research) using the classification rules in _schema.md. Most ingested sources become Ideas.

Create the primary note using the schema for that type:

• Generate kebab-case slug from title (max 60 chars)
• Write to KNOWLEDGE/<Type>/<slug>.md with proper frontmatter
• Include source_url: or source_path: in frontmatter
• MANDATORY: Include related: array with 2-4 typed links — the ripple pass (Step 3) identifies these, and they must be baked into the frontmatter of the primary note at creation time, not added after

Step 3 — Ripple pass (the key innovation)

Search for existing notes that relate to this new content:

# Search by extracted tags
rg -i "TAG1|TAG2|TAG3" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l --glob '!_*'

# Search by key entities/concepts mentioned
rg -i "ENTITY1|ENTITY2" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l --glob '!_*'

For each related note found (up to 10):

1. Read the note
2. Determine if the new source adds information, context, or contradicts existing claims
3. If yes, propose the specific update (add wikilink, add evidence, note contradiction)

Present the ripple plan to the user:

📥 INGEST RIPPLE PLAN:
  PRIMARY: Ideas/new-note-slug — "Title" (created)
  PRIMARY related: frontmatter links (MANDATORY):
    → Ideas/existing-note-1 — type: extends
    → Ideas/existing-note-2 — type: supports
    → People/person-slug — type: related
  RIPPLE (reverse-direction updates to existing notes):
    → Ideas/existing-note-1 — add body [[new-note-slug]] wikilink + add to its related: array (type: extends)
    → Ideas/existing-note-2 — update Evidence section with new data point + add to related:
    → Ideas/existing-note-3 — ⚠️ CONTRADICTION: new source says X, note says Y — type: contradicts
  NO CHANGE: Ideas/tangentially-related — mentioned same tag but no substantive connection

Step 4 — Execute ripple updates

After the user approves (or you determine updates are low-risk cross-references):

• Primary note: ensure related: frontmatter array has 2-4 typed entries — this is mandatory, not optional
• Related notes: add reverse-direction related: entries to their frontmatter with appropriate types
• Body wikilinks: add [[wikilinks]] in existing prose where natural (not forced)
• Update updated: date on modified notes
• For contradictions: add a > ⚠️ **Contradiction:** [note] claims X — see [[new-note]] for counter-evidence callout, AND add type: contradicts in related: arrays

Step 5 — Log and index

Append to KNOWLEDGE/_log.md: ```

• Source:
• Primary: /
• Ripple: N notes updated, N contradictions flagged

Regenerate MOCs:
```bash
bun ~/.claude/PAI/TOOLS/KnowledgeHarvester.ts index

Present in NATIVE mode.

Find and review conflicting claims across Knowledge notes.

Step 1 — Get contradiction candidates

Run the KnowledgeHarvester contradiction finder:

bun ~/.claude/PAI/TOOLS/KnowledgeHarvester.ts contradictions

This outputs pairs of notes with high tag overlap (2+ shared tags), ranked by overlap count.

Step 2 — Semantic review

For each pair (up to 10 highest-overlap pairs):

1. Read both notes
2. Extract key claims from each (Thesis, Evidence, Key Facts sections)
3. Check for:
   • Direct contradictions — Note A says X, Note B says not-X
   • Temporal supersession — Note A's claim is outdated by Note B's newer evidence
   • Scope conflicts — Both claim authority on the same topic but reach different conclusions

Step 3 — Report

Present findings:

🔍 CONTRADICTION SCAN:
  Pairs checked: N
  Contradictions found: N
  Superseded claims: N

  ⚠️ CONTRADICTION:
    [[note-a]] claims: "X"
    [[note-b]] claims: "Y"
    Resolution: [suggest which is correct, or flag for the user]

  📅 SUPERSEDED:
    [[older-note]] (2026-01-15): "X was true"
    [[newer-note]] (2026-03-20): "X is no longer true because Y"
    Action: Update older note with correction

Step 4 — Fix (with approval)

If the user approves resolutions:

• Update contradicted notes with correction callouts
• Update superseded notes with > 📅 **Updated:** See [[newer-note]] for current information
• Update updated: dates
• Regenerate MOCs

Present in NATIVE mode.

Navigate the Knowledge Archive as a graph.

No argument — stats overview:

bun ~/.claude/PAI/TOOLS/KnowledgeGraph.ts stats

Show node count, edge count, top clusters, most connected hubs, and isolated nodes.

With slug — traverse from a note:

bun ~/.claude/PAI/TOOLS/KnowledgeGraph.ts traverse <slug> --hops 2

Show all notes connected within 2 hops via tags, wikilinks, and typed relationships. Useful for exploring how knowledge connects across domains.

Related notes only:

bun ~/.claude/PAI/TOOLS/KnowledgeGraph.ts related <slug>

Present in NATIVE mode.

Compressed context retrieval over the Knowledge Archive using BM25-lite scoring.

bun ~/.claude/PAI/TOOLS/MemoryRetriever.ts "<query>" --top 5

Returns the top matching notes with compressed summaries, ranked by title match, tag overlap, and content frequency. Useful for loading relevant knowledge context without reading full files.

For raw excerpts without LLM compression:

bun ~/.claude/PAI/TOOLS/MemoryRetriever.ts "<query>" --raw

Present in NATIVE mode.

Mine recent conversations for memory candidates (decisions, preferences, milestones, problems).

bun ~/.claude/PAI/TOOLS/SessionHarvester.ts --mine --recent 10

Candidates are written to KNOWLEDGE/_harvest-queue/ for review — never directly to KNOWLEDGE/. Use /knowledge harvest to process the queue.

For dry run (preview only):

bun ~/.claude/PAI/TOOLS/SessionHarvester.ts --mine --recent 10 --dry-run

Present in NATIVE mode.

• 4 entity types now. People (human beings), Companies (organizations), Ideas (insights/theses/analyses), Research (multi-source investigations with methodology). If it doesn't fit one of these, it's not knowledge — it belongs in WORK/ or LEARNING/.
• Topic = tag, not domain. A security insight is an Idea with a security tag. Never create topic-based folders.
• The lookup test. "Would the user look this up by name?" — if not, it's not knowledge.
• Schema enforcement. Each entity type has required fields defined in _schema.md. Always read the schema before writing.
• Algorithm LEARN phase writes directly. The LEARN phase has the best context — it writes to KNOWLEDGE/ with proper schemas. Harvester reflections are disabled.
• Never delete notes without asking. Pruning is automatic (90-day seedling expiry via harvester). Manual deletion requires the user's approval.
• Wikilinks use strict kebab-case. [[prompt-injection]] not [[Prompt Injection]].
• All harvested notes start as seedlings. Only /knowledge develop promotes them.
• Temporal validity is optional. Notes can have valid_from/valid_until frontmatter fields to track when facts were true. The contradiction detector uses these to skip non-overlapping time windows.