Skip to content

Pinakes documentation

A portable, agent-first knowledge base. One directory = one KB.

Your documents and their sidecars are the source of truth; the index is derived state that can always be rebuilt. Retrieval — BM25, local embeddings, local reranking — runs entirely on your CPU and costs nothing, and a CI gate holds that promise rather than a sentence in a README.

The Pinakes were Callimachus's catalogue of the Library of Alexandria — the first known index of a body of knowledge.

This documentation is ordered simple → deep: start with the Guide, go deeper as you need.

  • Guide

    Install, stamp your first KB, index PDFs, search, keep the index fresh, wire it into an agent over MCP, and troubleshoot. No prior knowledge assumed.

    Guide

  • Reference

    Every command and flag with its exit codes, every pinakes.toml and sidecar field with its default, and the table mapping each promise this project makes to the test that holds it.

    CLI · Manifest · Verification

  • Concepts

    Why it is built this way: KB anatomy, storage, the retrieval pipeline, cost control, sync semantics and concurrency — with the trade-offs named, not hidden.

    Design · Updating an existing KB

  • Project

    What actually ships today, the measured numbers and when they were measured, the paid measurement runbook, the release procedure, and what every increment taught us.

    Status · Measurement run · Releasing · Retrospectives

  • Graph research

    Thirteen investigations — twelve external projects plus the in-house precedent — and the synthesis that turned them into a gated build order. Research, not specification: where it disagrees with Design, Design wins.

    Overview · The pinakes approach

Quickstart

uv add "pinakes[st]"                  # default backend
uv add "pinakes[light]"               # fastembed, no torch

pnk init my-kb                        # stamp a KB
pnk sync                              # index what changed (git-hook friendly)
pnk search "hybrid retrieval"         # free: BM25 + vector + rerank
pnk doctor                            # environment, coherence, orphans, link coverage

Two things pnk init cannot know

On a [light] install set provider = "fastembed" in both [embedding] and [rerank] — the model ids are identical on the two backends, so only provider moves. To index PDFs, add "**/*.pdf" to [sources] include. Both are in the Guide.

Reading paths

New here? Guide § Install → Your first KB → Searching → CLI reference.

Wiring it into an agent? Guide § Using it from an agent → pnk serve → Design § Retrieval.

Evaluating the design? Design → Status § Measured numbers → Verification → Graph research.

Spending money on scanned PDFs? Guide § Indexing PDFs → Design § Cost control → The measurement run.

What is true, and where it is written

One fact, one home. Every claim below lives in exactly one file; everywhere else links to it. This page is deliberately version-free — it says what Pinakes is, never which release you are on, so it does not go stale.

Question Answer lives in
Does this exist yet? Status — the only file in the repo that says what is built
What does this flag do? CLI; --help is authoritative, CLI adds when and why
What goes in pinakes.toml? Manifest and sidecar
How do I accomplish a task? Guide
Why is it built this way? Design
What holds this promise? Verification — and a test asserts each named test exists
What must never break? Invariants — the contracts that fail silently
What did we learn? Retrospectives

Elsewhere in the repo

  • Changelog — versioned release history
  • Build plans — the current build order, decision records and iteration logs
  • Docs routing table — which file to edit when an increment lands
  • CLAUDE.md — the conventions an agent working here must follow, and which plan is live