Active Memory PKB (Personal Knowledge Base)

pkb.md

PKB System Specification

Complete design specification for the Active Memory PKB system.

Overview

Active Memory PKB (Personal Knowledge Base) provides persistent memory for AI coding agents across sessions. It stores your coding standards, security patterns, and project-specific knowledge in human-readable Markdown files.

Design Principles:

• Agent-native - Optimized for OpenCode, Claude, and local LLMs
• Human-readable - 100% Markdown, no proprietary formats
• Portable - Git-friendly, sync across machines
• Token-efficient - Distilled knowledge, not raw logs

Physical Layer

The PKB repository is cloned to ~/.local/share/pkb/, keeping your "Senior Dev Brain" separate from the codebases you work on.

~/.local/share/pkb/                 # Clone the repo here
├── bin/
│   └── pkb                         # Installation script
├── docs/                           # Meta: system documentation
│   └── SPEC.md                     # This file
├── config/                         # Agent integration (symlinked at install)
│   ├── commands/                   # Symlinked to ~/.config/opencode/commands/
│   │   ├── pkb-init.md
│   │   ├── pkb-load.md
│   │   ├── pkb-remember.md
│   │   ├── pkb-commit.md
│   │   ├── pkb-review.md
│   │   └── pkb-search.md
│   └── skills/                     # Symlinked to ~/.config/opencode/skills/
│       ├── pkb-init/
│       │   └── SKILL.md
│       ├── pkb-load/
│       │   └── SKILL.md
│       ├── pkb-review/
│       │   └── SKILL.md
│       └── pkb-search/
│           └── SKILL.md
└── context/                        # Runtime knowledge (loaded by agent)
    ├── core/
    │   ├── principles/             # Always loaded by pkb-load
    │   │   ├── index.md            # Entry point - lists principles to load
    │   │   └── <principle>.md      # Additional principle files (user-defined)
    │   └── checklists/             # Loaded on demand by /pkb-review
    │       └── <checklist>.md      # Review criteria files (user-defined)
    └── projects/                   # Per-project memory
        └── [project-id]/           # Mapped via path relative to $HOME
            ├── context.md          # Distilled source of truth
            └── learnings.md        # Session scratchpad

Principles (context/core/principles/)

Your coding DNA - always loaded at session start via pkb-load.

File	Purpose
index.md	Entry point - philosophy and list of principle files to load
<principle>.md	Additional principle files (user-defined)

What belongs in principles:

• Coding style rules (naming, structure, patterns to follow)
• Security patterns (secrets handling, input validation, access control)
• Architectural preferences (simplicity vs abstraction, error handling)
• Anti-patterns to avoid (things you've learned cause problems)
• Agent behavioral guidelines (when to ask vs assume, verification steps)

These are standards you want applied to all projects. Project-specific knowledge goes in context/projects/<project-id>/context.md instead.

Example principle files:

File	Content Examples
code-style.md	Indentation rules, naming conventions, file organization
security.md	Secrets management, input validation, least privilege
error-handling.md	Fail-fast patterns, error propagation, logging standards
testing.md	Test structure, coverage expectations, mocking guidelines

index.md requirements:

The index.md file serves as the entry point. It must include an "Available Principles" table listing additional principle files to load:

## Available Principles

| File | Purpose |
|------|---------|
| `code-style.md` | Naming conventions and structure rules |
| `security.md` | Security patterns for all projects |

Checklists (context/core/checklists/)

Review criteria - loaded on demand by /pkb-review.

File	Purpose
<checklist>.md	Review criteria (user-defined)

Each checklist file contains items to verify during code review.

Example checklist files:

File	Content Examples
review.md	General code review criteria (error handling, idempotency)
deploy.md	Pre-deployment checks (migrations, rollback plan, feature flags)
api.md	API review criteria (versioning, error responses, auth)

Project Memory (context/projects/)

Dynamic, per-project knowledge:

File	Purpose
context.md	Distilled source of truth - architecture, gotchas, decisions
learnings.md	Session scratchpad - raw discoveries before consolidation

Project IDs are derived from the path relative to $HOME, with / replaced by --:

• ~/work/api → work--api
• ~/projects/client/frontend → projects--client--frontend

Projects must be under $HOME. Paths outside $HOME are not supported.

context.md template:

# <Project Name> - PKB Context

## Overview
Brief description of what this project does.

## Tech Stack
- Language: ...
- Framework: ...

## Structure
- `src/` - ...

## Architecture Notes
Key architectural decisions or patterns.

## Gotchas
Known issues, quirks, or warnings.

## History
- YYYY-MM-DD: PKB initialized

learnings.md template:

# Learnings

<!-- Session discoveries are appended here via /pkb-remember -->
<!-- Run /pkb-commit to merge into context.md -->

Command Layer

Explicit actions defined in config/commands/ (symlinked to agent's commands directory during installation). These force the agent to perform specific memory operations.

Command File Format

Commands are Markdown files in config/commands/ with YAML frontmatter:

---
description: One-line description shown in command listings
---

Instructions for the agent when the command is invoked.

## Steps

1. Step one
2. Step two

$ARGUMENTS

Element	Purpose
description	Shown in agent's command list
Body	Instructions executed when command runs
$ARGUMENTS	Placeholder replaced with user-provided arguments

Naming convention: pkb-<verb>.md

/pkb-load

Purpose: Explicitly load PKB context into the current session.

Logic:

1. Loads the pkb-load skill
2. Follows the skill's instructions to read all principle and project files
3. Confirms what was loaded

Usage:

/pkb-load

Note: This command is a thin wrapper around the pkb-load skill. The skill can auto-trigger at session start, but this command provides explicit invocation.

/pkb-init

Purpose: Initialize PKB for the current project. Spawns an init agent.

Logic:

1. Derives project ID from path relative to $HOME (with / → --)
2. Spawns sub-agent with general type, passing project ID and directory, instructing it to load pkb-init skill
3. Sub-agent checks if already initialized, scans codebase if not, creates context files
4. Displays results returned by sub-agent

Usage:

/pkb-init

/pkb-remember [fact]

Purpose: Quick capture of a discovery or gotcha.

Logic:

1. Derives project ID from path relative to $HOME (with / → --)
2. Verifies PKB is initialized for this project (suggest /pkb-init if not)
3. If [fact] is provided: Appends timestamped entry to learnings.md
4. If no argument: Scans session history for discoveries (gotchas, API quirks, architecture insights), presents numbered list, asks user which to save, appends selected items

Entry Format:

## [YYYY-MM-DD HH:MM]

<the fact/discovery>

Usage:

/pkb-remember The legacy API expects dates in MM-DD-YYYY format
/pkb-remember   # (no argument) - extracts learnings from session history

/pkb-commit

Purpose: Maintenance step - consolidate learnings into permanent context.

Logic:

1. Derives project ID from path relative to $HOME (with / → --)
2. Verifies PKB is initialized for this project
3. Reads learnings.md - if empty or header only, report nothing to commit
4. Analyzes learnings and merges into appropriate context.md sections:
   • Gotchas: Specific warnings, quirks, "don't do this" items
   • Architecture Notes: Design decisions, patterns, structural insights
   • Tech Stack: New dependencies or tools discovered
   • History: Always add dated entry summarizing what was learned
5. Clears learnings.md (reset to header template)
6. Reports what was merged
7. Offers to git commit - if confirmed, stages and commits with message pkb(<project-id>): consolidate session learnings

History Entry Format:

- YYYY-MM-DD: Brief summary of learnings consolidated

learnings.md Reset Template:

# Learnings

<!-- Session discoveries are appended here via /pkb-remember -->
<!-- Run /pkb-commit to merge into context.md -->

Usage:

/pkb-commit

/pkb-review

Purpose: Code review against PKB principles. Spawns a review agent.

Logic:

1. Derives project ID from path relative to $HOME (with / → --)
2. Spawns sub-agent with explore type, passing project ID and directory, instructing it to load pkb-review skill
3. Sub-agent loads principles, checklists, and project context, reviews code, returns findings
4. Displays findings returned by sub-agent

Usage:

/pkb-review

/pkb-search [query]

Purpose: Search across all project memories. Spawns a search agent.

Logic:

1. Derives project ID from path relative to $HOME (with / → --)
2. Spawns sub-agent with explore type, passing project ID and query, instructing it to load pkb-search skill
3. Sub-agent searches all PKB markdown files, returns grouped results
4. Displays results returned by sub-agent

Usage:

/pkb-search CORS nginx
/pkb-search date format legacy

Skill Layer

Agent capabilities defined in config/skills/ (symlinked to agent's skills directory during installation). These are tools the agent uses automatically or when asked.

Skill File Format

Skills are directories in config/skills/ containing a SKILL.md file:

config/skills/pkb-<name>/
└── SKILL.md

The SKILL.md uses YAML frontmatter:

---
name: pkb-<name>
description: Description shown in skill listings
---

## What This Skill Does

High-level purpose.

## Execution Steps

1. Step one
2. Step two

Element	Purpose
name	Skill identifier (must match directory name)
description	Shown in agent's skill list
Body	Instructions when skill is loaded

Naming convention: Directory pkb-<name>/ containing SKILL.md

pkb-load (Boot Sequence)

The most critical skill - loads PKB principles into the conversation.

Action:

1. Reads index.md from context/core/principles/, then loads each file listed in its "Available Principles" table
2. Derives project ID from path relative to $HOME (with / → --)
3. Reads context.md and learnings.md from context/projects/<project-id>/ if they exist
4. Does NOT load context/core/checklists/ (that's for /pkb-review only)

After Loading:

• Apply loaded principles to all code suggestions
• Flag concerns based on loaded principle files
• Suggest /pkb-remember when discovering gotchas
• Suggest /pkb-commit before session ends

Trigger: Should run automatically at session start.

pkb-init (Init Agent)

Skill loaded by the init sub-agent when /pkb-init is invoked.

Action:

1. Receives project ID and directory from calling agent
2. Checks if context/projects/<project-id>/ exists - if so, return existing context summary
3. Scans codebase to understand structure, tech stack, patterns
4. Creates project folder and generates context.md and learnings.md
5. Returns confirmation with summary of what was captured

Guidelines:

• Keep context.md concise - distill findings, don't dump raw data
• Focus on information useful for future sessions
• Note any immediate gotchas discovered during scan
• If project is empty or minimal, note that in context

Trigger: Spawned by primary agent via /pkb-init command.

pkb-review (Review Agent)

Skill loaded by the review sub-agent when /pkb-review is invoked.

Action:

1. Receives project ID and directory from calling agent
2. Loads all principle files from context/core/principles/
3. Loads all checklists from context/core/checklists/
4. Loads project context.md if exists
5. Reviews code against all loaded criteria:
   • Each principle file becomes a check category
   • Each checklist file becomes a section
   • Project context checks for regressions against known gotchas
6. Returns findings grouped by category

Output Format:

## PKB Review

### <Principle Category>
- [ ] Issue: <description with file:line>
- [x] Pass: <what was checked>

### <Checklist Name>
- [ ] <check item>: <finding>

### Summary
Overall assessment. Priority issues first.

### Suggested /pkb-remember
New gotchas discovered during review.

Guidelines:

• Be specific: include file paths and line numbers
• Prioritize findings by severity
• If principle files are sparse, note that standards need defining

Trigger: Spawned by primary agent via /pkb-review command.

pkb-search (Search Agent)

Skill loaded by the search sub-agent when /pkb-search is invoked.

Action:

1. Receives project ID and query from calling agent
2. Searches all .md files in context/core/ and context/projects/*/
3. Matches filenames and content (case-insensitive)
4. Groups results: Core standards first, then current project, then other projects
5. Returns formatted summary

Output Format:

## PKB Search Results for: "<query>"

### Core Standards
- **<filename>**: "...matching context..."

### Current Project: <project-id>
- **context.md**: "...matching context..."

### Other Projects

#### <other-project-id>
- **context.md**: "...matching context..."

---
Found X matches across Y locations.

Guidelines:

• Show 2-3 lines of context around each match
• If no matches found, report that clearly
• If many matches in one location, summarize rather than listing all

Trigger: Spawned by primary agent via /pkb-search command.

Installation

The bin/pkb script manages symlinks between PKB and agent config directories.

Usage

./bin/pkb                        # Install for default agent
./bin/pkb install --agent <name> # Install for specific agent
./bin/pkb uninstall              # Remove symlinks
./bin/pkb --help                 # Show usage

Install Behavior

1. Creates agent's commands directory if missing
2. Creates agent's skills directory if missing
3. Symlinks each config/commands/*.md to agent's commands directory
4. Symlinks each config/skills/*/ to agent's skills directory

Uninstall Behavior

Removes symlinks created by install. Leaves non-symlink files untouched.

Adding Agent Support

Add the agent's commands and skills directory paths to the script, then update the usage text and dispatch logic. See existing agent implementations as reference.

Integration Protocol

Rules for agents using the PKB system:

1. Startup

ALWAYS execute pkb-load at the start of a session.

2. Context Awareness

If a solution contradicts context/core/principles/, you must explain why the deviation is necessary.

3. Capture Discoveries

When finding a "gotcha" in legacy code or discovering something important, suggest using /pkb-remember to capture it.

4. Maintenance

Before closing a session, ask if the user wants to run /pkb-commit to consolidate session learnings.

Workflow Example

A typical session with a legacy codebase:

1. Start: You cd into a 10-year-old PHP repository

2. Initialize: Agent runs pkb-load, finds no project folder, suggests running /pkb-init

3. Discovery: You realize the database is shared with an old Perl script

   /pkb-remember Database is shared with 'legacy-perl-script'; avoid changing the 'users' table schema
   

4. Work: You write a new feature

5. Review: You run /pkb-review. The agent catches that you didn't use parameterized queries as defined in your security principles

6. Close: You run /pkb-commit. The agent updates the project's context.md so next time you open this repo, the Perl script warning is front-and-center

Syncing Across Machines

The PKB directory is a git repository. Push to a private remote:

cd ~/.local/share/pkb
git remote add origin git@github.com:youruser/pkb.git
git push -u origin main

On a new machine:

git clone git@github.com:youruser/pkb.git ~/.local/share/pkb
cd ~/.local/share/pkb
./bin/pkb install