vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/docs/knowledge.md
iris 972a3ead68 docs(knowledge): document hive-wide knowledge repo + /knowledge bind-mount 
The internal/knowledge forge repo and its /knowledge container bind-mount
have been live since feat(#1167) but had no docs/ entry — only a mention
in the agent system prompt.

Add docs/knowledge.md covering:
- Agent access (/knowledge read-only bind-mount inside every container)
- Repository layout (internal/knowledge, auto-seeded README)
- Sync mechanism (webhook on push + periodic pull fallback)
- State paths (/var/lib/hyperhive/knowledge on host)
- Contribution workflow (fork + PR, no direct push)

Also add a file-map entry and reading-path bullet in CLAUDE.md.
2026-06-05 16:56:00 +02:00

2.8 KiB
Raw Blame History

Hive-wide knowledge repository

internal/knowledge on the forge is a shared reference doc repo readable by every agent. hive-c0re clones it to the host and bind-mounts the clone read-only into every agent container at /knowledge.

Agent access

Inside any agent container:

/knowledge/          # read-only bind-mount of the local clone
/knowledge/README.md # table of contents (seeded on first use)

Agents read documents directly from that path. The mount is read-only — agents never write through it. To contribute, fork internal/knowledge on the forge, open a PR, and the operator merges it. The local clone updates automatically on merge (see Sync mechanism below).

Repository layout

Canonical forge location: internal/knowledge (org internal, repo knowledge). Every agent's forge account is a read-only collaborator; the core account has push access for auto-seeding.

The repo is auto-created at hive-c0re startup if it doesn't exist, seeded with a README.md containing a contribution guide and a blank table of contents. Add an entry to that ToC each time you create a new document.

Sync mechanism

hive-c0re maintains the local clone at /var/lib/hyperhive/knowledge via two paths:

  1. Forgejo push webhook — ensure_webhook registers a push hook on internal/knowledge at startup pointing at http://127.0.0.1:<dashboard_port>/webhook/knowledge. On any push to main (including merge commits) hive-c0re runs git pull so agents see the new content on their next turn. The endpoint is loopback-only; no signature verification is needed.

  2. Periodic pull — a background task in hive-c0re::main pulls on a fixed cadence as a fallback (webhook missed, c0re restarted between pushes). The pull is best-effort — a failure logs a warning and does not affect the rest of the daemon.

The local clone is created (or refreshed) once at startup via knowledge::ensure_local_clone. If the repo is brand new and empty, ensure_local_clone seeds it with the default README before returning.

State

  • Host clone: /var/lib/hyperhive/knowledge — persists across hive-c0re restarts and agent destroy/recreate. Deleted only by manual operator action.
  • In-container mount: /knowledge — bind-mounted read-only from the host clone on every container start. Gone when container is stopped; reappears on next start with the current clone state.

Contributing

  1. Fork internal/knowledge into your own namespace on the forge.
  2. Create a branch and add or update a document.
  3. Open a pull request — the operator reviews and merges.
  4. The webhook fires on merge; every running container sees the updated content within seconds.

Do not push directly to main — agents have read-only collaborator access and the push will be rejected.