mj-deving Knowledge
PAI's persistent knowledge base. Stores curated content as flat markdown files with YAML frontmatter in ${AGENT_HOME}/knowledge/entries/. Grep-based search. No database. Zero context footprint until invoked — content lives outside the conversation entirely.
Customization
Before executing, check for user customizations at:
${PAI_USER_DIR}/SKILLCUSTOMIZATIONS/Knowledge/
If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. If the directory does not exist, proceed with skill defaults.
Architecture
${AGENT_HOME}/knowledge/
INDEX.md # Auto-maintained index (one line per entry)
entries/ # Flat markdown files with YAML frontmatter
2026-04-18-my-note.md
2026-02-28-pai-v4-upgrade.md
kn.ts # CLI tool (Bun/TypeScript, single file)
~/.local/bin/kn # Symlink, in PATH
No database. No MCP server. No running process. Files are greppable, human-readable, and git-trackable. context-search (Source I) searches this directory automatically.
Entry Format
---
title: "Descriptive title"
category: insight # insight | decision | reference | pattern | session-summary
tags: [tag1, tag2, tag3]
project: project-name # optional — which project this relates to
created: 2026-04-18
---
Freeform markdown content here.
When to Use
Save (manual — user asks or you recommend)
| User Says | Action |
|---|---|
| "save this" / "remember this" | Save the most recent output to knowledge base |
| "save to knowledge" | Same as above |
| "store this as a pattern" | Save with category pattern |
| "save that research" | Save with category reference |
Save (proactive — after producing these outputs, ASK if user wants to save)
| After Producing | Suggest Category |
|---|---|
| ExtractWisdom output | insight |
| Research results | reference |
| Follow-builders digest | reference |
| Architecture decision | decision |
| Reusable approach or technique | pattern |
| Important insight or analysis | insight |
Do NOT auto-save without asking. Say: "Want me to save this to the knowledge base?" If the user previously said "always save digests" etc., honor that.
Search (when context would help)
| User Says | Action |
|---|---|
| "what do I know about X" | kn search "X" |
| "recall / find / look up" | kn search with relevant terms |
| "search knowledge for X" | kn search "X" |
| "what was that insight about Y" | kn search "Y" |
Proactive Search (search BEFORE answering when these conditions are met)
- User asks about a topic that sounds like it was discussed before
- User references "that digest" or "that research" without specifics
- A new task overlaps with previously saved content
CLI Reference
Save
# From content string
kn save --title "Title" --cat <category> --tags "tag1,tag2" --project "project-name" --content "..."
# From stdin pipe (for large content)
echo "content" | kn save --title "Title" --cat <category> --tags "tag1,tag2"
Categories: insight, decision, reference, pattern, session-summary
Search
kn search "natural language query" # Full-text grep search
kn search --cat decision "deployment" # Category-filtered
kn search --tags security "API" # Tag-filtered
kn search --limit 5 "agents" # Limit results
Returns filename, title, category, tags, and a content snippet around the match.
Browse & Retrieve
kn list # All entries (title + category + date)
kn list --cat pattern # Filtered by category
kn get <filename> # Full content (supports partial name match)
kn recent [N] # Last N entries (default 10)
kn categories # List categories with counts
kn stats # Entry count, size, date range
kn delete <filename> # Remove entry and update INDEX.md
Saving Guidelines
Title
Descriptive, searchable. Encode the what — future-you searches by topic, not date.
- Good: "Why we chose Bun over Node for ClaudeClaw"
- Good: "Exfiltration guard regex false positive patterns"
- Bad: "Digest" or "Research results"
Tags
Comma-separated, lowercase. Include people, concepts, projects mentioned.
- Good:
bun,runtime,decision,claudeclaw - Bad:
interesting,good,important
Category Selection
| Category | When to use | Example |
|---|---|---|
insight |
Aha moments, learnings, things to remember | "SHA-256 with salt is insufficient for short PINs" |
decision |
Why X was chosen over Y, with rationale | "Chose Grammy over Telegraf because..." |
reference |
Procedures, commands, how-tos, digests | "How to deploy ClaudeClaw to VPS" |
pattern |
Reusable approaches, techniques | "Per-chat FIFO queue pattern for Telegram bots" |
session-summary |
Session wrapup summaries | "PAI v4.0.1 Upgrade Completion" |
Content
Save the distilled version, not raw transcripts. Write for future reference — include the why, not just the what. Context and rationale outlast bare facts.
Project Tag
Use --project when the knowledge is specific to a project (e.g., claudeclaw, cortex, pai). Omit for cross-cutting knowledge.
Integration with Other Skills
After ExtractWisdom
"Want me to save this to the knowledge base?"
→ kn save --title "Wisdom: [source]" --cat insight --tags "..." --project "..."
After Research
"Want me to save these findings?"
→ kn save --title "[research topic]" --cat reference --tags "..." --project "..."
After follow-builders
"Want me to save today's digest?"
→ kn save --title "AI Builders Digest [date]" --cat reference --tags "..."
Before a New Task
When a user starts work on something that might overlap with saved knowledge:
kn search "relevant terms"
Surface any relevant prior content before diving in.
With context-search
Knowledge entries are automatically searched by /cs and /context-search (Source I). No manual integration needed — when a user searches for prior work, knowledge base entries surface alongside PRDs, commits, and conversation history.