65 lines
4.3 KiB
Markdown
65 lines
4.3 KiB
Markdown
# Albok — the fleet knowledgebase
|
|
|
|
**Service:** `http://albok.nh3.internal:8392` (= `10.100.50.44:8392`, albok-service on nh3-albok)
|
|
**CLI:** `albok` · **MCP (Claude Code):** `albok-mcp`, registered at user scope · **Owner:** `albok-dev` (althing)
|
|
|
|
One searchable store of what the fleet knows: every repo's `persistent-memory.md` (entries, detail
|
|
files, archives), the stash, the library (books by chapter, papers, extracted concepts), and the operator's own
|
|
knowledgebase (his notes vault and his inbox). Search
|
|
is hybrid (vector + keyword) and LLM-free.
|
|
|
|
## Access
|
|
|
|
Every nh3-dev shell carries `ALBOK_SERVICE` and `ALBOK_TOKEN` — the shared **`fleet-agents` read
|
|
token**: `fleet/*` (memory, stash), `library/*` (fiction, nonfiction) and the operator's knowledgebase,
|
|
`personal/notes` and `personal/inbox` (Prime, 2026-10-19: every agent must be able to read it). Anything classed
|
|
`personal`, `adult` or `secret` stays hidden from it; it does not read `personal/agent-feedback` or the sealed wing.
|
|
A shell older than 2026-10-19 may lack them; open a new one. A handle that needs more grants asks
|
|
infra-ops for its own token.
|
|
|
|
```sh
|
|
albok status # the wings this token reads, and their states
|
|
albok search "why did we drop the reset endpoint" # --wing fleet/memory --top-k 20 --facet key=value
|
|
albok read <object_id> # pristine bytes to stdout; lineage notes on stderr
|
|
albok sidecar <object_id> # provenance: repo, file, commit, section, entry date
|
|
albok related <object_id> # links, similar, same source, shared concepts — each with its reason
|
|
```
|
|
|
|
Claude Code sessions get the same verbs as tools (`albok_search`, `albok_read`, `albok_sidecar`,
|
|
`albok_related`, `albok_status`, …). Codex and Grok use the CLI.
|
|
|
|
## Reading the answers right
|
|
|
|
- **Never threshold on score.** The null floor (~0.031) sits just under real hits (~0.033); rank, don't cut.
|
|
- **Coverage is reported, read it.** A reply lists `searched`, `locked` and `degraded` wings: an
|
|
empty result over a degraded wing is not "nothing exists". An unreachable service is an
|
|
outage, never an empty result (the client says which).
|
|
- **Hidden by default:** objects classed `adult`, `personal` or `secret` are hidden from every
|
|
reader; `--include CLASS` opts back in only where the token holds that class grant.
|
|
- **Supersession is declared, not inferred.** Every object has a permanent `uid` (in every search hit).
|
|
A read of an entry names what supersedes it (`superseded by …`); an empty lineage means "none
|
|
declared", not "current". When your new memory entry replaces an older one, end it with
|
|
`Supersedes [[<uid>]]` (the old entry's uid; a detail file may be named by its stem) and leave
|
|
the old entry as written.
|
|
|
|
## Writing into it (nobody writes to the service directly)
|
|
|
|
Nemi, albok's ingester, walks every source hourly on nh3-dev (a user timer, a few minutes past the hour):
|
|
|
|
| You want to add | Do this |
|
|
|---|---|
|
|
| a decision, lesson or state for a repo | write it in that repo's `persistent-memory.md` under `~/development/` (Nemi reads the file on disk; commit it as usual) |
|
|
| raw material (a transcript, an article) | `/stash` (Claude) or a file in `~/stash/` with its frontmatter |
|
|
| a document for the operator's knowledgebase | a markdown file in `/srv/nemi/inbox/` (wing `personal/inbox`; kept as dropped, never moved; PDFs are coming) |
|
|
| a book | `scp book.epub lkraven@nh3-dev:/srv/nemi/books/fiction/` (or `nonfiction/`): validated, then shelved into `~/library/` and ingested the same hour, or moved to `rejected/` beside a reason file (`not_epub`, `drm`, `duplicate`, …); `LOG` records every decision |
|
|
|
|
## When to reach for it
|
|
|
|
When the operator asks you something his own notes might cover, search his knowledgebase first
|
|
(`--wing personal/notes --wing personal/inbox`, or no `--wing` for everything you can read), read several hits whole,
|
|
and build the answer from them, citing the object ids. Before you decide something, check whether it was already decided, tried or measured, in this repo
|
|
or any other. Before you research a game-design, cognition or fiction question, check the library.
|
|
|
|
*Detail:* `~/development/albok/README.md`, `packages/albok-client/README.md` (CLI and MCP),
|
|
`packages/albok-nemi/README.md` (sources, the book drop). Health: `scripts/albok-check` in that repo.
|