Agent Knowledge Base

Purpose

Leverage accumulated knowledge in ~/doc/agent-kb to avoid redundant code research. Add new entries when discoveries warrant preservation.

When to Use

•Encountering unfamiliar code patterns, services, or architecture
•When user asks questions outside training data that would require code research
•Before extensive codebase research—check KB first
•When explicitly asked to save or update knowledge
•When a topic has been researched and should be preserved

Feeding Discoveries Back

After significant code exploration, consider what was learned:

•New knowledge: Something not in the KB → offer to create entry
•Corrective knowledge: Code contradicts KB → flag and offer to update
•Confirmatory knowledge: Code confirms KB → no action needed (optionally note verification)

If KB contradicts code: Stop and report the discrepancy. Ask: "KB says X, but code shows Y - should I update the KB?" Do not silently ignore KB errors.

End of exploration prompt: "Did we discover anything worth preserving or correcting in the KB?"

KB Location

code

~/doc/agent-kb/

Querying the KB

•
List available entries:
bash
```
ls -1 ~/doc/agent-kb/
```
•
Search by tag or keyword:
bash
```
grep -l "pattern" ~/doc/agent-kb/*.md
```
•
Read relevant entries before researching code.

File Naming Convention

code

YYYYMMDDThhmmss--title-in-lowercase-alphanumeric__tag1_tag2_tagN.md

•Timestamp: date +%Y%m%dT%H%M%S
•Title: lowercase, alphanumeric, hyphens only
•
Tags: lowercase alphanumeric, underscore-separated, after double-underscore, no hyphens
code

Examples:

•20260128T133522--example-flow__ref.md
•20260126T144226---architecture-notes__component1_component2_tag3.md

Creating KB Entries

•
Generate timestamp:
bash
```
date +%Y%m%dT%H%M%S
```
•
Create file with frontmatter matching filename:
markdown
```
---
title:      Title In Title Case
date:       YYYY-MM-DD Day HH:MM
tags:       [tag1, tag2]
identifier: YYYYMMDDThhmmss
verified:   YYYY-MM-DD
source:     code-inspection | documentation | verbal | inferred
---

# Title

Content here.
```
Provenance fields:
- •verified: Date last confirmed against code (update on confirmation)
- •
  source: How the knowledge was obtained
  - •code-inspection - directly verified in source code
  - •documentation - from internal docs (Confluence, etc.)
  - •online - from external online documentation
  - •verbal - expert opinion, discussion, tacit knowledge
If a source has a URL (online or documentation), add a ## Sources section at the bottom of the document with the citation(s).
•
Keep entries focused—one topic per file.
•
Link to other KB entries using denote:{identifier} - e.g., "See denote:20260130T171856 for query details"
•
Don't automatically follow cross-references - Only load referenced documents if directly relevant to the current question.

Updating KB Entries

When knowledge becomes stale or incomplete:

•Read the existing entry
•Update content in place
•Preserve the original identifier and filename
•Update verified date in frontmatter if re-confirmed against code
•Add verified and source fields to frontmatter if missing from older entries

What Belongs in the KB

•Only verifiable knowledge from existing code - no design alternatives, proposals, or "we could do X" speculation. Code is the source of truth.