From f006046d141febf61803fc1f052e72543553c410 Mon Sep 17 00:00:00 2001 From: OpenCode Test Date: Sun, 28 Dec 2025 22:21:15 -0800 Subject: [PATCH] Add PA knowledge base design and handoff docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .../2025-12-28-pa-knowledge-base-design.md | 135 +++++++++++++++++ .../2025-12-28-pa-knowledge-base-handoff.md | 103 +++++++++++++ state/future-considerations.json | 138 ++++++++++++++++++ 3 files changed, 376 insertions(+) create mode 100644 docs/plans/2025-12-28-pa-knowledge-base-design.md create mode 100644 docs/plans/2025-12-28-pa-knowledge-base-handoff.md create mode 100644 state/future-considerations.json diff --git a/docs/plans/2025-12-28-pa-knowledge-base-design.md b/docs/plans/2025-12-28-pa-knowledge-base-design.md new file mode 100644 index 0000000..b9d1acb --- /dev/null +++ b/docs/plans/2025-12-28-pa-knowledge-base-design.md @@ -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 ""` - Add fact to appropriate KB +- `--fact .=` - Structured addition +- `--list-facts` - Show KB contents +- `--list-facts ` - 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 diff --git a/docs/plans/2025-12-28-pa-knowledge-base-handoff.md b/docs/plans/2025-12-28-pa-knowledge-base-handoff.md new file mode 100644 index 0000000..e3cfc55 --- /dev/null +++ b/docs/plans/2025-12-28-pa-knowledge-base-handoff.md @@ -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 "" # 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: + +```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 diff --git a/state/future-considerations.json b/state/future-considerations.json new file mode 100644 index 0000000..851bd11 --- /dev/null +++ b/state/future-considerations.json @@ -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." + } + ] +}