f006046d14
- 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>
104 lines
3.0 KiB
Markdown
104 lines
3.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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":
|
|
|
|
```markdown
|
|
### 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:
|
|
|
|
```markdown
|
|
### Knowledge Base
|
|
|
|
```
|
|
/pa --fact "<description>" # Add fact (PA determines category)
|
|
/pa --fact <cat>.<key>=<value> # Add structured fact
|
|
/pa --list-facts # Show all KB contents
|
|
/pa --list-facts <category> # Show specific category
|
|
```
|
|
```
|
|
|
|
### 5. Update CLAUDE.md
|
|
|
|
Add to "Shared State Files" table:
|
|
|
|
```markdown
|
|
| `~/.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:
|
|
|
|
1. Test lazy-load: `/pa what cluster type do we run?` should read KB and answer "k0s"
|
|
2. Test fact addition: `/pa --fact net.dns=pihole` should update KB
|
|
3. Test implicit learning: Correct PA on a fact, confirm it offers to save
|
|
4. 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
|