claude-code/docs/plans/2025-12-28-pa-knowledge-base-design.md

PA Knowledge Base Design

Status: Approved Date: 2025-12-28 Author: PA + User brainstorm session

Problem

PA makes assumptions about infrastructure facts (e.g., assumed k3s instead of k0s) when it could check a local knowledge base first. As PA expands to handle non-tech tasks (target: 50%+), it needs a lightweight fact store that doesn't bloat the context window.

Design Decisions

Architecture

Two knowledge bases:

KB	Location	Writers	Readers	Content
Shared	~/.claude/state/kb.json	PA only	PA, k8s-*, sysadmin, all agents	Infrastructure facts
PA-private	~/.claude/state/personal-assistant/kb.json	PA only	PA only	Personal, non-tech facts

Format

Minified JSON - All state files use minified format (no prettification). ~10% token savings; no human readers.

Categorized with terse keys:

{"infra":{"cluster":"k0s","nodes":3,"arch":"arm64"},"svc":{"gitops":"argocd","mon":"prometheus"},"net":{"domain":"local","ingress":"traefik"},"hw":{"pi5":2,"pi3":1}}

Initial categories:

Key	Purpose	Example facts
infra	Cluster/platform	cluster type, node count, architecture
svc	Services/tools	gitops, monitoring, alerting
net	Network	domain, ingress controller, DNS
hw	Hardware	device models, RAM, storage

Loading Strategy

Lazy-load - PA reads KB only when needed, not at session start.

Session caching - Once a category is loaded, cache in context for the session.

Query priority - For factual questions: check KB before web search.

Learning Behavior

Hybrid approach:

1. Explicit: /pa --fact "cluster is k0s" or /pa --fact infra.cluster=k0s
2. Implicit: When PA is corrected on a fact, it asks: "Want me to add this to the KB?"

User confirms before any write.

Access Control

• PA is the sole writer to both KBs
• Domain agents (k8s-*, sysadmin, etc.) read shared KB only
• Domain agents cannot request additions; they are passive consumers
• Domain agents have static context in their instruction files; KB is for dynamic facts

File Format Specification

Shared KB (~/.claude/state/kb.json)

{"infra":{},"svc":{},"net":{},"hw":{}}

Values should be primitives (string, number, boolean) or flat arrays. Avoid nested objects beyond category level.

PA-private KB (~/.claude/state/personal-assistant/kb.json)

Same format. Categories TBD based on future non-tech use cases. Initial empty structure:

{}

Implementation Changes

1. Create KB files

• ~/.claude/state/kb.json with initial categories
• ~/.claude/state/personal-assistant/kb.json empty

2. Update PA agent instructions

Add to ~/.claude/agents/personal-assistant.md:

• KB file locations and access patterns
• Lazy-load behavior description
• Learning behavior (explicit + implicit)
• New /pa --fact command

3. Update /pa command

Add to ~/.claude/commands/pa.md:

• --fact "<fact>" - Add fact to appropriate KB
• --fact <category>.<key>=<value> - Structured addition
• --list-facts - Show KB contents
• --list-facts <category> - Show specific category

4. Update CLAUDE.md

Add KB files to shared state table.

5. Document in state-schemas.md

Add KB schema documentation.

6. Minify existing state files

Convert all ~/.claude/state/*.json to minified format.

Future Considerations

• fc-012: Session caching mechanism (in progress via this design)
• fc-013: Vector database for semantic search (deferred)

Out of Scope

• Agent-to-agent KB requests (agents are passive consumers)
• Automatic fact expiration/staleness detection
• KB versioning or history

Testing

After implementation:

1. PA should check KB before making infrastructure assumptions
2. /pa --fact should add facts correctly
3. Correction detection should offer to save facts
4. Domain agents should be able to read shared KB