# 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