972a3ead68
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.
75 lines
2.8 KiB
Markdown
75 lines
2.8 KiB
Markdown
# 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](#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.
|