# Knowledge Subsystem — AGENTS.md

Operating brief for any agent (Claude Code, scripted compiler, lint job) touching the vault.

## Scope
- Write episodic capture to `knowledge/daily/` via scripts/hooks only.
- Compiled durable pages live under `knowledge/notes/` (flat or typed subdirs).
- Do not write to `knowledge/raw/` or `knowledge/inbox/` except when staging sources.
- Promotion of generalized insights uses the `bridge-promote-insight` skill — never inline ad-hoc moves that break provenance.

## Layers
- `knowledge/daily/YYYY-MM-DD.md` — append-only raw capture from session hooks (PreCompact, SessionEnd). Immutable log; do not rewrite.
- `knowledge/notes/*.md` (and optional `{concepts,decisions,patterns,debugging,qa}/`) — compiled durable pages.
- `knowledge/index.md` — navigation over knowledge pages. Regenerated by `scripts/rebuild_memory_index.py`.
- `knowledge/log.md` — append-only editorial changelog.
- `$LLM_WIKI_STATE_ROOT/run/state.json` — machine state for automation (last-flush, last-compile, per-file hashes, dedupe). Default: the vault itself → `run/state.json`. Runtime lives inside the vault under gitignored `cache/logs/run/` dirs.
- `$LLM_WIKI_STATE_ROOT/logs/` — lint reports, compile stdout/stderr logs, SessionStart debug dumps. Also runtime, gitignored.

## Page conventions
Every knowledge page:
- `# Title`
- `One-sentence summary: ...`
- `## Lesson` (or `## Decision`, `## Symptom / Cause / Resolution`, etc.)
- `## Evidence` — pointer to `knowledge/daily/<date>.md` and `[HH:MM:SS]` block
- `## Related` — wikilinks to sibling notes pages

## What to lift into knowledge
Lift an item only if it is:
- reusable beyond the session it came from,
- not already derivable from code, config, or existing notes,
- specific enough to act on ("when X, do Y because Z").

Do NOT lift:
- status updates, task progress,
- restatements of file paths or code structure,
- speculation not validated by use,
- summaries of `knowledge/raw/` / `knowledge/inbox/` material (those belong in notes after compile).

## Categories
- **concepts/** — noun-shaped mental models.
- **decisions/** — dated choice + alternatives rejected + reason. Immutable; supersede, don't edit.
- **patterns/** — verb-shaped recurring approach.
- **debugging/** — symptom → cause → resolution.
- **qa/** — settled answer to a non-obvious recurring question.

Flat notes under `knowledge/notes/*.md` with `type:` frontmatter are also valid.

Tiebreak: patterns > concepts; debugging > qa.

## Automation contract
- `scripts/flush_memory.py` — classifies a session transcript into FLUSH_MAJOR / FLUSH_MINOR / FLUSH_OK.
- `scripts/compile_memory.py` — compiles changed daily logs into knowledge pages with VERIFY-BEFORE-WRITE.
- `scripts/codex_memory.py daily-log` — Codex heartbeat or full flush path.
- `scripts/user_prompt_capture.py` / `post_tool_capture.py` — non-LLM breadcrumbs (secrets redacted).
- `scripts/lint_memory.py` — structural + OKF checks over `knowledge/notes/`, `skills/`, and `rules/`. Use `--scope all` (default) or `--scope wiki`.
- Recursion guard: hook wrappers short-circuit when `CLAUDE_INVOKED_BY` is set.

## Multi-tool integration
- **Claude Code** — hooks in `integrations/claude-code/settings.json` (SessionStart, UserPromptSubmit, PreCompact, PostToolUse, SessionEnd).
- **OpenCode** — plugin `scripts/llm-wiki-memory-opencode.js`.
- **Codex CLI** — `scripts/codex_memory.py` + `codex-memory-wrapper.ps1`.

## Boundary: daily vs notes
Promote from `knowledge/daily/` (via compile) into `knowledge/notes/` only when the insight is durable and reusable. See `docs/operating-model.md`.
