Files

OpenCode Test f006046d14 Add PA knowledge base design and handoff docs

- Design doc: two-KB architecture (shared + PA-private)
- Lazy-load with session caching
- Minified JSON format for all state files
- Hybrid learning (explicit + implicit with confirmation)
- Handoff doc for next session implementation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2025-12-28 22:21:15 -08:00

3.0 KiB

Raw Blame History

Handoff: PA Knowledge Base Implementation

Date: 2025-12-28 Design Doc: ~/.claude/docs/plans/2025-12-28-pa-knowledge-base-design.md Status: Ready for implementation

Context

User and PA brainstormed a knowledge base system so PA can check local facts before making assumptions or querying the web. Design is approved.

Implementation Tasks

1. Create KB files

# Shared KB - infrastructure facts
echo '{"infra":{"cluster":"k0s","nodes":3,"arch":"arm64"},"svc":{"gitops":"argocd","mon":"prometheus","alerts":"alertmanager"},"net":{},"hw":{"pi5_8gb":2,"pi3_1gb":1}}' > ~/.claude/state/kb.json

# PA-private KB - empty for now
echo '{}' > ~/.claude/state/personal-assistant/kb.json

2. Minify all existing state JSON files

Convert these to single-line minified format:

~/.claude/state/system-instructions.json
~/.claude/state/future-considerations.json
~/.claude/state/model-policy.json
~/.claude/state/autonomy-levels.json
~/.claude/state/personal-assistant-preferences.json
~/.claude/state/personal-assistant/general-instructions.json
~/.claude/state/personal-assistant/session-context.json
~/.claude/state/sysadmin/session-autonomy.json

Use: jq -c . file.json > tmp && mv tmp file.json

3. Update PA agent (`~/.claude/agents/personal-assistant.md`)

Add section after "Memory Management":

### Knowledge Base

**Files:**
- Shared: `~/.claude/state/kb.json` (read/write)
- Private: `~/.claude/state/personal-assistant/kb.json` (read/write)

**Behavior:**
- Lazy-load KB when needed, not at session start
- Check KB before web search for factual questions
- Cache loaded categories within session

**Learning:**
- Explicit: `/pa --fact "..."` adds to KB
- Implicit: When corrected, offer to save fact with user confirmation

4. Update `/pa` command (`~/.claude/commands/pa.md`)

Add to flags section:

### Knowledge Base

/pa --fact "" # Add fact (PA determines category) /pa --fact .= # Add structured fact /pa --list-facts # Show all KB contents /pa --list-facts # Show specific category

5. Update CLAUDE.md

Add to "Shared State Files" table:

| `~/.claude/state/kb.json` | Shared knowledge base | personal-assistant |

6. Update state-schemas.md

Add KB schema documentation.

7. Update future-considerations.json

Change fc-012 status from "designing" to "implementing" or "resolved".

Verification

After implementation:

Test lazy-load: /pa what cluster type do we run? should read KB and answer "k0s"
Test fact addition: /pa --fact net.dns=pihole should update KB
Test implicit learning: Correct PA on a fact, confirm it offers to save
Verify domain agents can read: Spawn k8s-diagnostician, have it reference KB

Notes

All state JSON files are now minified (no prettification)
PA is sole writer to both KBs
Domain agents are passive consumers (read-only, no requests)
Keep values as primitives or flat arrays; avoid deep nesting

3.0 KiB Raw Blame History