Skip to content

README.md

Latest commit

 

History

History
52 lines (41 loc) · 3.42 KB

README.md

File metadata and controls

52 lines (41 loc) · 3.42 KB
Raw

agent-knowledge/ — shared agent knowledge home

The harness-neutral source of truth for everything agents read before they grep a repo: protocols, topic learnings, tool guides, the knowledge-home scripts, and usage telemetry. It is shared by all runtimes (Factory Droid, Claude Code, and any CLI agent that can read files and run shell).

Edit canonical files here — never duplicate them into a runtime-specific dir. A runtime points at this home; it does not own a private copy.

Layout

Dir Contents
references/ Always-load protocols (the index.md catalog, log.md chronology) + topic learnings (learnings-*.md) + tool guides. The hand-curated Karpathy LLM Wiki-style knowledge base (see references/README.md).
scripts/ knowledge-search.sh (search bd memories + learnings + domain docs), drift-check.sh (staleness warnings), learn.sh (one-liner learning capture), codex-dispatch.sh (cross-runtime sub-agent parity), codex-session-prime.sh (Codex SessionStart bd-prime hook), auto-consolidate.sh (scheduled consolidation runner). The knowledge scripts honor the HARNESS_REFS env var and default to this home's references/.
metrics/ Usage telemetry written by the learning-gate hook: per-file read counts (learning-reads.json/.jsonl, primary) + per-entry citation counts (learning-usage.json/learning-citations.jsonl). Drives consolidation ranking + gap-detection (never pruning). See metrics/README.md.
reading/ External-source reading notes (distilled, vetted articles/papers/talks) — a separate trust tier from references/ (external, curated, not yet proven in your stack). Written by the ingest-reading skill; cataloged in reading/index.md.

How each runtime reaches it

  • Factory Droid — its historical paths (the runtime's references/ and scripts/ dirs) are symlinks into this home, so Factory keeps working unchanged.
  • Claude Code — its CLAUDE.md/AGENTS.md, agents, skills, and hooks reference these paths directly.
  • Generic runtimes — point at the home with the HARNESS_REFS env var (the scripts honor it) or a symlink from wherever the runtime expects its references.

Not stored here

  • bd / beads operational memory — task state, comments, and per-session bd remember notes. That store is tool-agnostic and lives in the repo's .beads database (git-synced, so it is shared across runtimes via the repo, not via this home).
  • Runtime-specific config trivia — settings, hook wiring, and machine-local facts belong in that runtime's own dir / native memory, not here.

See references/learnings-*.md for durable engineering patterns and core/protocols/bd-and-memory.md → "Memory routing" for which store to use for what.

Deployment note

This agent-knowledge/ directory is the template for the deployed home. At install time you create a real home — e.g. ~/.agent-knowledge/{references,scripts,metrics,reading} (any path works) — copy or seed these contents into it, and point every runtime at that path (Factory via symlinks, Claude via direct paths, generic via HARNESS_REFS). Runtime wiring lives in adapters/ and installation/.