Agentic Knowledge Units
Agentic Knowledge Units (AKU) provide deterministic, local-first project memory. Callers store durable work products as Knowledge Units, then search them or build bounded context packs without an LLM or vector database.
Implemented lifecycle
flowchart TB A[Initialize or load the AKU root] --> K[Create, update, fork, discard, or delete Knowledge Units] K --> R[Record events, documents, files, folders, links, runs, results, validations, and sessions] R --> I[Update aggregate indexes with locked atomic transactions] I --> Q[Search records or resolve a scoped context graph] Q --> C[Build a character-budgeted ContextPack] classDef lifecycle fill:#f5f1ff,stroke:#6657b8,color:#2d246b; classDef storage fill:#eef4ff,stroke:#1c4f9c,color:#0f2557; classDef result fill:#eefbf4,stroke:#28875d,color:#174c38; class A,K lifecycle; class R,I storage; class Q,C result;
AgenticKnowledgeUnits.mjs implements the public lifecycle and delegates schemas, storage, indexing, lexical ranking, locking, recovery, and context-pack construction to modules under AgenticKnowledgeUnits/internal/. AgenticKnowledgeUnits.d.ts publishes the matching TypeScript surface.
Current public surface
| Area | Methods |
|---|---|
| Root and KU lifecycle | initAKU, loadAKU, exists, initKU, loadKU, updateKUState, setKUStatus, forkKU, discardKU, deleteKU |
| Evidence records | recordEvent, recordDocument, registerFile, registerFolderScope, recordResult, recordRun, recordValidation |
| Relationships and sessions | linkKU, unlinkKU, resolveContextGraph, ingestSession, discardSession |
| Retrieval | search, buildContextPack, buildScopedContextPack, and list methods for each indexed record family |
| Integrity | updateIndexes, rebuildIndexes, and doctor |
Storage and retrieval guarantees
AKU uses local JSON and JSONL records, aggregate indexes, advisory locks, and atomic writes. The constructor's rootDir remains the project boundary for registered files and folders. An optional persistenceRoot independently owns every AKU record, aggregate index, lock, and pending transaction; omitting it retains the non-Ploinky <rootDir>/.aku default. Storage, atomic writes, and locks share a canonical persistence location captured at construction and revalidated before reads, recovery, writes, and deletion. Redirecting any ancestor is rejected even when the selected project lies inside private storage and shares a lower parent with AKU. Pre-existing canonical aliases above the workspace, such as macOS /var, remain supported; cached instances and transaction callbacks do not bypass later checks. A symlinked root, including an explicit alias at <rootDir>/.aku, is rejected, and the owned pending, kus, and lock paths reject symbolic links before access or removal. Search uses deterministic lexical scoring with filters, bounded per-KU diversity, and optional explanations. Context packs enforce a character budget and may include state, history, linked units, explicit units, and folder-scoped candidates according to supplied options.
Discarded or obsolete material is excluded from normal retrieval unless the caller opts into audit-oriented filters. Physical deletion requires explicit confirmation. doctor() and automatic repair support recoverable index and storage inconsistencies; they do not turn AKU into semantic retrieval or decide what knowledge is valid.