pi-aurora-knowledge

A local semantic knowledge base for the Pi coding agent. Point it at a folder of documents; the agent can then search, read, and file into it by meaning rather than filename.

Everything runs on your machine. Nothing is uploaded.

Setup

Two commands. The first brings up the stack, the second gives Pi the tools.

npx pi-aurora-knowledge up
pi install npm:pi-aurora-knowledge

up scaffolds ./aurora-knowledge/ (compose file, .env, and a library/ folder), builds the images, and waits until the API answers. The first run takes a few minutes to build; later runs are seconds.

Then drop files into aurora-knowledge/library/. Top-level folders become categories:

library/
├── notes/
├── contracts/
└── research/

Anything readable is chunked, embedded, and indexed within a few seconds — no import step.

Requirements

• Docker Desktop (or Docker Engine + Compose v2)
• Node 20+
• An embeddings model. By default the stack uses Docker Model Runner:

  docker model pull ai/qwen3-embedding:0.6B-F16
  

  If you would rather use Ollama or OpenAI, .env has ready-to-uncomment blocks.

Commands

npx pi-aurora-knowledge up	Scaffold if needed, build, start, wait for health
npx pi-aurora-knowledge down	Stop the stack (your documents and vectors are kept)
npx pi-aurora-knowledge logs [service]	Follow logs
npx pi-aurora-knowledge status	Container health
npx pi-aurora-knowledge init [dir]	Scaffold only, without starting

Tools Pi gets

Tool	Description
kb_search	Semantic search; returns scored passages with source paths
kb_read	Read a full document by library-relative path
kb_categories	List categories with file and chunk counts
kb_documents	List indexed documents, optionally by category
kb_add_note	Save a markdown note into a category
kb_status	Vector count, embedding model, indexing errors
kb_delete	Delete a document — only registered when AURORA_KB_ALLOW_DELETE=true

A bundled aurora-knowledge skill teaches the agent when to reach for them.

Why not MCP? Pi ships no MCP client — a deliberate design decision. These are native Pi tools calling the REST API. The server does also expose MCP at /mcp/ for other clients such as Claude Desktop.

Configuring Pi

Only needed if you changed a default:

Variable	Default	Purpose
AURORA_KB_URL	http://127.0.0.1:8077	Set this if you changed KB_PORT
AURORA_KB_API_KEY	(unset)	Only if you set KB_REQUIRE_AUTH=true
AURORA_KB_SEARCH_LIMIT	8	Default passages per search
AURORA_KB_ALLOW_DELETE	(unset)	true registers the destructive kb_delete tool

Using your own documents folder

Rather than copying files into library/, point at a folder you already have. In aurora-knowledge/.env:

LIBRARY_PATH=/Users/me/Documents/notes

Then npx pi-aurora-knowledge up. The folder is mounted read-write — kb_add_note writes into it, and kb_delete (if enabled) deletes from it.

Choosing an embedding model

EMBEDDING_DIM must match the model, or Qdrant rejects the vectors.

Model	EMBEDDING_DIM
qwen3-embedding:0.6B-F16 (DMR)	1024
nomic-embed-text (Ollama)	768
text-embedding-3-small (OpenAI)	1536

Changing models after indexing means rebuilding the collection:

npx pi-aurora-knowledge down
docker volume rm aurora-knowledge_qdrant_data aurora-knowledge_kb_state
npx pi-aurora-knowledge up

Troubleshooting

The API never comes up. Almost always embeddings. npx pi-aurora-knowledge logs kb-indexer will show a connection error to DMR_BASE_URL or an unknown model name.

Search returns nothing. Ask Pi for kb_status. Zero vectors means nothing indexed yet — check that files are inside library/ and under KB_MAX_FILE_MB.

Wrong vector dimensions. EMBEDDING_DIM does not match your model. Fix it, then rebuild the collection as above.

Security

The API binds to 127.0.0.1 only, so auth is off by default. If you expose the port, set KB_REQUIRE_AUTH=true and KB_API_KEY in .env (a key is pre-generated for you), and give Pi the same value as AURORA_KB_API_KEY.

Skills and extensions run with full access to your machine — the standard caveat for any Pi package. The source is in extensions/ and is short enough to read.

License

MIT