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>
This commit is contained in:
OpenCode Test
135
docs/plans/2025-12-28-pa-knowledge-base-design.md
Normal file
135
docs/plans/2025-12-28-pa-knowledge-base-design.md
Normal file
@@ -0,0 +1,135 @@
|
|||||||
|
# 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:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"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`)
|
||||||
|
|
||||||
|
```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:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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
|
||||||
103
docs/plans/2025-12-28-pa-knowledge-base-handoff.md
Normal file
103
docs/plans/2025-12-28-pa-knowledge-base-handoff.md
Normal file
@@ -0,0 +1,103 @@
|
|||||||
|
# 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
|
||||||
138
state/future-considerations.json
Normal file
138
state/future-considerations.json
Normal file
@@ -0,0 +1,138 @@
|
|||||||
|
{
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "Deferred features and decisions for future implementation",
|
||||||
|
"items": [
|
||||||
|
{
|
||||||
|
"id": "fc-001",
|
||||||
|
"category": "infrastructure",
|
||||||
|
"title": "Workstation monitoring with Prometheus",
|
||||||
|
"description": "Deploy node_exporter and Alertmanager for workstation metrics and alerting",
|
||||||
|
"priority": "medium",
|
||||||
|
"status": "deferred",
|
||||||
|
"created": "2024-12-28",
|
||||||
|
"notes": "Would enable proactive alerting for disk, memory, CPU issues"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-002",
|
||||||
|
"category": "agent",
|
||||||
|
"title": "Network admin agent",
|
||||||
|
"description": "Agent for network configuration, firewall rules, VPN management",
|
||||||
|
"priority": "medium",
|
||||||
|
"status": "deferred",
|
||||||
|
"created": "2024-12-28",
|
||||||
|
"notes": "Would manage iptables/nftables, NetworkManager, WireGuard"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-003",
|
||||||
|
"category": "agent",
|
||||||
|
"title": "Personal assistant agent",
|
||||||
|
"description": "Agent for personal tasks, reminders, scheduling",
|
||||||
|
"priority": "medium",
|
||||||
|
"status": "deferred",
|
||||||
|
"created": "2024-12-28",
|
||||||
|
"notes": "Integration with calendar, task management"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-004",
|
||||||
|
"category": "integration",
|
||||||
|
"title": "External LLM integration",
|
||||||
|
"description": "Support for non-Claude models in the agent system",
|
||||||
|
"priority": "low",
|
||||||
|
"status": "deferred",
|
||||||
|
"created": "2024-12-28",
|
||||||
|
"notes": "For specialized tasks or cost optimization"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-005",
|
||||||
|
"category": "optimization",
|
||||||
|
"title": "Model usage logging and cost tracking",
|
||||||
|
"description": "Track model usage across agents for cost analysis",
|
||||||
|
"priority": "medium",
|
||||||
|
"status": "deferred",
|
||||||
|
"created": "2024-12-28",
|
||||||
|
"notes": "Would help optimize model selection policy"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-006",
|
||||||
|
"category": "design",
|
||||||
|
"title": "Slash commands redesign",
|
||||||
|
"description": "Revisit slash command architecture and user experience",
|
||||||
|
"priority": "low",
|
||||||
|
"status": "deferred",
|
||||||
|
"created": "2024-12-28",
|
||||||
|
"notes": "Current design may need refinement"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-007",
|
||||||
|
"category": "optimization",
|
||||||
|
"title": "Document structure optimization",
|
||||||
|
"description": "Optimize agent document format for efficiency",
|
||||||
|
"priority": "low",
|
||||||
|
"status": "deferred",
|
||||||
|
"created": "2024-12-28",
|
||||||
|
"notes": "Balance between clarity and token usage"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-008",
|
||||||
|
"category": "infrastructure",
|
||||||
|
"title": "ArgoCD CLI authentication",
|
||||||
|
"description": "Configure argocd CLI with proper authentication",
|
||||||
|
"priority": "medium",
|
||||||
|
"status": "resolved",
|
||||||
|
"created": "2025-12-28",
|
||||||
|
"resolved": "2025-12-28",
|
||||||
|
"notes": "Using 10-year API token (expires 2035-12-26). Token ID: e3980c6a-1c4e-4f1a-8459-a120a5c60cc5. Stored in ~/.config/argocd/config. No renewal automation needed."
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-009",
|
||||||
|
"category": "infrastructure",
|
||||||
|
"title": "Prometheus local port-forward",
|
||||||
|
"description": "Document Prometheus access patterns for agents",
|
||||||
|
"priority": "low",
|
||||||
|
"status": "identified",
|
||||||
|
"created": "2025-12-28",
|
||||||
|
"notes": "Prometheus not accessible on localhost:9090. Options: (1) use kubectl exec to query, (2) set up port-forward, (3) use ingress. Currently works via pod exec."
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-010",
|
||||||
|
"category": "infrastructure",
|
||||||
|
"title": "Clone homelab gitops repo locally",
|
||||||
|
"description": "Clone git@github.com:will666/homelab.git for git-operator access",
|
||||||
|
"priority": "low",
|
||||||
|
"status": "resolved",
|
||||||
|
"created": "2025-12-28",
|
||||||
|
"resolved": "2025-12-28",
|
||||||
|
"notes": "Cloned to ~/.claude/repos/homelab"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-011",
|
||||||
|
"category": "k8s-health",
|
||||||
|
"title": "Address OutOfSync ArgoCD apps",
|
||||||
|
"description": "5 apps OutOfSync, 1 Degraded (porthole)",
|
||||||
|
"priority": "medium",
|
||||||
|
"status": "identified",
|
||||||
|
"created": "2025-12-28",
|
||||||
|
"notes": "OutOfSync: adopt-a-street, ai-stack, gitea, home-assistant, kubernetes-dashboard, speetest-tracker. Degraded: porthole"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-012",
|
||||||
|
"category": "agent-memory",
|
||||||
|
"title": "PA knowledge base with session caching",
|
||||||
|
"description": "Local KB for infrastructure facts with lazy-load and in-session caching",
|
||||||
|
"priority": "medium",
|
||||||
|
"status": "designed",
|
||||||
|
"created": "2025-12-28",
|
||||||
|
"notes": "Design complete. See docs/plans/2025-12-28-pa-knowledge-base-design.md. Handoff ready for implementation."
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "fc-013",
|
||||||
|
"category": "agent-memory",
|
||||||
|
"title": "Vector database for agent long-term memory",
|
||||||
|
"description": "Semantic search over agent knowledge using embeddings",
|
||||||
|
"priority": "low",
|
||||||
|
"status": "deferred",
|
||||||
|
"created": "2025-12-28",
|
||||||
|
"notes": "Would enable fuzzy matching, semantic queries, and scalable knowledge storage. Consider: ChromaDB, Qdrant, or pgvector."
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user