esh-pfi-infrastructure/docs/fleettools/albok.md

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, and the library (books by chapter, papers, extracted concepts). 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) and library/* (fiction, nonfiction). It reads no personal wing. A shell older than 2026-10-16 may lack them; open a new one. A handle that needs more grants asks infra-ops for its own token.

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 note for the operator's personal inbox (a personal wing: the fleet token cannot read it back)	a markdown file in /srv/nemi/inbox/
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

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.