Knowledge Base

The knowledge base is a lightweight document store built into the codepakt server. Agents write to it, read from it, and search it using cpk docs. It’s not a vector database — it’s a simple tagged document store backed by the same SQLite instance as the task board.

Document types

Four types, each with a distinct purpose:

Type	Use case
operational	How-to guides, runbooks, current procedures
decision	ADRs, why-we-chose-X records, tradeoff notes
reference	API specs, schema docs, external references, the PRD
learning	Insights agents discover during work — patterns, gotchas, undocumented behavior

The distinction matters for search and retrieval. When an agent needs to understand how something currently works, it searches operational. When it needs to understand why an architectural decision was made, it searches decision. When it discovers something unexpected about the codebase, it writes a learning doc.

Writing documents

cpk docs write \
  --type learning \
  --title "JWT refresh token rotation pattern" \
  --body "When issuing a new refresh token, the old one must be invalidated in the same transaction. See src/auth/tokens.ts line 87. If not done atomically, concurrent requests can reuse an old token during the window between read and write." \
  --tags "auth,jwt,security"

Document created: doc_042
Type: learning
Tags: auth, jwt, security

All flags:

Flag	Required	Description
--type	yes	operational, decision, reference, or learning
--title	yes	Document title
--body	yes	Document content (markdown supported)
--section	no	Section heading within the document
--tags	no	Comma-separated tags for search filtering
--author	no	Author name (defaults to CPK_AGENT value)

Searching

cpk docs search "auth" --type reference

doc_001  [reference]  Project PRD                    tags: product
doc_009  [reference]  Auth API contract              tags: auth,api
doc_031  [reference]  JWT token spec                 tags: auth,jwt

Full-text search across title, body, and tags. Filter by type to narrow results.

cpk docs search "why postgres" --type decision

doc_017  [decision]  Database selection rationale    tags: infra,db

Listing documents

cpk docs list --type decision

ID       TYPE      TITLE                              AUTHOR   TAGS
doc_017  decision  Database selection rationale       backend  infra, db
doc_022  decision  Monorepo vs separate repos         sameer   architecture
doc_034  decision  Use Hono over Express              backend  api, framework

Reading a document

cpk docs read doc_017

Title: Database selection rationale
Type: decision
Author: backend
Tags: infra, db
Created: 2025-03-10

We evaluated SQLite, Postgres, and PlanetScale. For v0.1 (single-user,
self-hosted), SQLite with WAL mode satisfies all requirements with zero
operational overhead. Postgres is planned for v0.2 when team/concurrent
access is needed.

Alternatives considered:
- Postgres: correct for multi-user but overkill for single-user local setup
- PlanetScale: managed cost, external dependency, not offline-capable

How init uses the knowledge base

When you run cpk init --prd ./PRD.md, the server:

1. Reads the PRD file content
2. Stores it as a reference doc titled “Project PRD”
3. Creates an operational doc titled “Board Setup Guide” with the coordination workflow

Any agent can then retrieve the PRD:

cpk docs search "PRD"
cpk docs read doc_001

This means agents don’t need the PRD injected into their context directly — they pull it on demand, costing tokens only when needed.

Agent usage pattern

A well-instrumented agent workflow looks like this:

Before starting work on a task:

cpk docs search "auth" --type reference    # read the spec
cpk docs search "auth" --type operational  # read how it's currently done

After completing work:

cpk docs write \
  --type learning \
  --title "Session token edge case on mobile Safari" \
  --body "iOS Safari aggressively purges localStorage on tab close. Use sessionStorage + a service worker keep-alive for mobile auth sessions." \
  --tags "auth,mobile,safari"

When making a non-obvious architectural decision:

cpk docs write \
  --type decision \
  --title "Why we cache tokens in Redis not the DB" \
  --body "DB-based token blacklisting adds a query to every authenticated request. At our scale (10k req/min) this doubles DB load. Redis cache with 15-min TTL matching token lifetime eliminates this." \
  --tags "auth,redis,performance"

The knowledge base is how agents build up shared context over time without relying on a single massive system prompt.