AI Agent Persistent Knowledge System - Universal Template
Version: 1.0
Purpose: Reusable knowledge management system for AI-assisted software development
Applicable to: Any codebase with AI agent interaction (OpenCode, Cursor, GitHub Copilot, etc.)
What This System Does
Gives AI agents persistent memory across sessions by automatically loading structured knowledge files at startup and saving discoveries during work.
Result: AI agents never forget critical information, saving 10-15 minutes of context explanation per session.
Quick Start (30 minutes setup)
Step 1: Create File Structure (5 minutes)
# From your project root
mkdir -p docs/domain
mkdir -p docs/ai
mkdir -p docs/adr
# Create core files
touch AGENTS.md
touch docs/domain/README.md
touch docs/ai/MEMORY.md
touch docs/ai/TASKLOG.md
touch docs/ai/KNOWLEDGE_VERIFICATION.md
Step 2: Copy AGENTS.md Template (10 minutes)
Create AGENTS.md in your project root with this content:
# Agent Guidelines for [PROJECT_NAME]
## 🧠 AI Memory Protocol (MANDATORY)
This repository uses a **layered knowledge system** to separate business logic from engineering knowledge.
You MUST treat the following as first-class artifacts:
- `docs/domain/*.md` - Business logic, domain rules, feature behavior (long-lived)
- `docs/ai/MEMORY.md` - Engineering knowledge: debug recipes, performance patterns, gotchas (long-lived)
- `docs/ai/TASKLOG.md` - Current task scratchpad (short-lived, cleared per task)
- `docs/adr/*.md` - Architecture decisions with trade-offs (long-lived, optional)
### Startup Behavior (Every Session)
Before doing any work, you MUST:
1. Read `AGENTS.md` (this file)
2. Read `docs/ai/MEMORY.md` (engineering knowledge)
3. Read `docs/domain/README.md` (domain index)
4. Read relevant `docs/domain/*.md` files for features you'll work on
5. Read `docs/ai/TASKLOG.md` (if present)
Then you MUST **OUTPUT** a "✅ Context Loaded" message that includes:
- Domain areas you read
- 3-7 key constraints relevant to the current task (from both engineering and domain knowledge)
- Known gotchas that may affect the work
**Example format**:
✅ Context Loaded
Domain areas: authentication, payments Key constraints:
- User sessions expire after 24 hours
- Payment processing uses Stripe webhooks (async)
- Database queries should use pagination for lists > 100 items
Known gotchas:
- JWT tokens not invalidated on logout (stateless design)
- Webhook retries can cause duplicate processing (use idempotency)
**This checkpoint proves you loaded context before starting work.**
### Knowledge Layer Separation (CRITICAL)
#### Quick Decision Tree
When you discover new information, ask yourself:
**Q1: "If the codebase was deleted, would this knowledge help rebuild it?"**
→ **YES** = Business logic → `docs/domain/*.md`
- Examples: "Users can have multiple payment methods", "Orders require email confirmation"
→ **NO** = Engineering knowledge → `docs/ai/MEMORY.md`
- Examples: "Use connection pooling for database", "Run tests with --parallel flag"
**Q2: "Will I need this information next week?"**
→ **NO** = Temporary → `docs/ai/TASKLOG.md`
- Examples: "Hypothesis: bug in line 45", "Stack trace shows..."
→ **YES** = Permanent → Continue to Q3
**Q3: "Is this a structural choice with trade-offs?"**
→ **YES** = Architecture decision → `docs/adr/*.md`
- Examples: "Chose PostgreSQL over MongoDB because...", "Use event sourcing for audit trail"
→ **NO** = Go back to Q1
#### What Goes Where
**Write to `docs/domain/*.md` (Business Logic)**:
- ✅ Entity relationships and state machines
- ✅ Business rules and validation logic
- ✅ Feature workflows and state transitions
- ✅ API behavior and integration contracts
- ✅ Edge cases and special scenarios
- ✅ Metric definitions and calculations
- ❌ NOT debug commands or performance tips
**Write to `docs/ai/MEMORY.md` (Engineering Knowledge)**:
- ✅ Performance optimization patterns
- ✅ Debug recipes and troubleshooting steps
- ✅ Known gotchas and traps
- ✅ Code conventions and file structure
- ✅ Test framework usage
- ✅ Integration quirks (API rate limits, etc.)
- ❌ NOT business rules or feature behavior
**Write to `docs/ai/TASKLOG.md` (Current Work)**:
- ✅ Investigation steps, hypotheses, dead ends
- ✅ Debug commands and results
- ✅ Local reproduction steps
- ✅ Stack traces and root causes
- ✅ Temporary notes (clear at end of task)
**Write to `docs/adr/*.md` (Architecture Decisions)**:
- ✅ Structural changes with trade-offs
- ✅ Technology choices with rationale
- ✅ Long-term consequences
- ✅ Alternatives considered
### During Work (Continuous) - AUTOMATIC DOCUMENTATION
**CRITICAL**: Documentation updates are NOT optional - they happen AUTOMATICALLY as you discover information.
When you discover new information, you MUST IMMEDIATELY categorize and save it:
**Is it about HOW features work?** → **IMMEDIATELY** update `docs/domain/*.md`
- Entity relationships, state machines, business rules
- Feature workflows, validation logic
- API behavior, integration contracts
- Edge cases, metric definitions
**Is it about HOW to debug/optimize?** → **IMMEDIATELY** update `docs/ai/MEMORY.md`
- Performance patterns, debug recipes
- Known gotchas, code conventions
- Test framework usage, integration quirks
**Is it temporary investigation notes?** → **IMMEDIATELY** update `docs/ai/TASKLOG.md`
- Investigation steps, hypotheses, dead ends
- Debug commands, reproduction steps
- Stack traces, root causes
**Is it a structural decision?** → **IMMEDIATELY** create/update `docs/adr/*.md`
- Structural changes with trade-offs
- Technology choices with rationale
- Long-term consequences, alternatives considered
**DO NOT wait until "end of task" to document** - save knowledge the moment you discover it.
### End-of-Iteration Behavior (Mandatory)
At the end of every meaningful iteration (bug found, decision made, approach chosen), you MUST:
1. ✅ Confirm `docs/ai/TASKLOG.md` has current progress
2. ✅ Confirm `docs/domain/*.md` has all discovered business rules
3. ✅ Confirm `docs/ai/MEMORY.md` has all engineering insights
4. ✅ Show diffs of ALL changed documentation files
**If any documentation layer is missing updates, go back and add them before proceeding.**
### Strictness Rules
- Never write vague memory. Every entry must be actionable.
- ALWAYS include source references (file paths, line numbers, or source doc names).
- Keep domain docs focused on WHAT the system does, not HOW to debug it.
- Keep MEMORY.md focused on HOW to work with the code, not WHAT it does.
- Never duplicate - if business logic is in domain docs, just reference it from MEMORY.
### Confidence Markers
Use these markers when adding knowledge to indicate verification status:
- ✅ **VERIFIED** - Confirmed by code inspection, tests, or production behavior
- ⚠️ **HYPOTHESIS** - Reasonable assumption based on evidence, not yet confirmed
- 🔍 **NEEDS VERIFICATION** - Contradictory evidence exists, requires investigation
- 📅 **AS OF [date]** - Time-sensitive information that may change
**Examples**:
```markdown
## User Authentication Flow
⚠️ HYPOTHESIS: Session tokens are stored in Redis with 24-hour TTL
📅 AS OF 2024-01-15: No explicit TTL found in code, inferred from config
Source: config/session.rb, observation in development
## Payment Processing
✅ VERIFIED: Stripe webhooks are processed asynchronously via background jobs
Source: app/jobs/process_stripe_webhook_job.rb:15-45, spec/jobs/process_stripe_webhook_job_spec.rb:23
Verified: 2024-01-15
Contradiction Detection
If you discover information that contradicts existing documentation:
- ⚠️ STOP and flag the contradiction clearly
- Investigate which version is correct (check code, tests, production logs)
- Update ALL affected documentation files
- Show diffs with "CONTRADICTION RESOLVED" marker in commit/update message
- Add note explaining the resolution
Never silently overwrite contradicting information without investigation and explanation.
Documentation is Part of the Deliverable
CRITICAL: If you are about to propose a final solution, you MUST first confirm that the appropriate knowledge layers are updated and show the diffs.
If you implement code changes without updating the correct documentation layer, that is considered incomplete work.
Session Handoff Protocol
If you must stop work mid-task (interrupted, blocked, or passing to another agent):
-
Update
docs/ai/TASKLOG.mdwith:- Summary of what was accomplished
- What's currently in progress (unfinished)
- Next steps to continue the work
- Any blockers, questions, or uncertainties
- Hypotheses that need verification
-
Commit any domain/MEMORY updates immediately (don't leave knowledge uncommitted)
-
Mark incomplete items clearly with status indicators
Format:
## Current Task: [Task Name]
### Completed
- ✅ Item 1
- ✅ Item 2
### In Progress
- 🔄 Item 3 (50% complete - waiting for X)
### Next Steps
1. Continue with item 3 after resolving X
2. Then move to item 4
### Blockers
- Missing API credentials for testing
- Need clarification on expected behavior for edge case Y
Benefit: Next agent reads TASKLOG.md and continues seamlessly without losing context.
🛠️ Build, Test & Lint Commands
[PROJECT-SPECIFIC: Add your commands here]
Running Tests
# Run all tests
[YOUR_TEST_COMMAND]
# Run specific test file
[YOUR_TEST_COMMAND] path/to/test_file
# Run tests with coverage
[YOUR_COVERAGE_COMMAND]
Linting & Code Quality
# Run linter
[YOUR_LINT_COMMAND]
# Auto-fix issues
[YOUR_LINT_FIX_COMMAND]
Development Server
# Start development server
[YOUR_DEV_SERVER_COMMAND]
📝 Code Style Guidelines
[PROJECT-SPECIFIC: Add your style guidelines]
File Structure
- [Your conventions]
Naming Conventions
- [Your conventions]
Code Organization
- [Your conventions]
🔒 Git Rules
NEVER commit or stage changes automatically:
- ❌ Do NOT run
git commitwithout explicit user approval - ❌ Do NOT run
git addor stage any changes - ❌ Do NOT create commits as part of completing tasks
- ✅ DO show
git difforgit statusto explain changes - ✅ DO let user know when work is complete for their review
Rationale: Users need full control over git operations for review and workflow management.
### Step 3: Create Domain Index (5 minutes)
Create `docs/domain/README.md`:
```markdown
# Domain Knowledge Index
This directory contains business logic, domain rules, and feature documentation for [PROJECT_NAME].
## Purpose
Domain documentation is separated from engineering knowledge to maintain clear boundaries:
- **Domain docs** (`docs/domain/`) - Business rules, entity relationships, state machines, feature behavior
- **Engineering knowledge** (`docs/ai/MEMORY.md`) - Performance patterns, debug recipes, code conventions
- **Architecture decisions** (`docs/adr/`) - Structural changes with trade-offs and rationale
## Domain Areas
[Start with your most important features, add more as you document them]
### Core Features
- **[feature1.md](./feature1.md)** - [Brief description]
- **[feature2.md](./feature2.md)** - [Brief description]
### Supporting Features
- **[feature3.md](./feature3.md)** - [Brief description]
## How to Use This Documentation
### For Development Work
1. Identify the feature area you're working on
2. Read the relevant domain doc to understand business rules
3. Check `docs/ai/MEMORY.md` for engineering gotchas
4. Reference source code locations provided in each doc
### For Bug Investigation
1. Start with domain docs to understand expected behavior
2. Use debug recipes in `docs/ai/MEMORY.md` for troubleshooting
3. Check ADRs for architectural context if needed
### For Adding New Features
1. Read related domain docs to understand existing patterns
2. Follow code conventions from `AGENTS.md`
3. Create an ADR if making structural changes
4. Update domain docs with new business rules
## Documentation Standards
Each domain doc follows this structure:
- **Overview** - High-level feature description
- **Entities** - Key models and their relationships
- **States & Transitions** - State machines and workflows
- **Business Rules** - Validated constraints and logic
- **Edge Cases** - Known exceptional scenarios
- **API Behavior** - External integrations and contracts
- **Source References** - File paths with line numbers
All rules must include source references (file paths) from code or investigation docs.
Step 4: Initialize MEMORY.md (5 minutes)
Create docs/ai/MEMORY.md:
# Engineering Knowledge (Durable)
This file contains reusable **engineering knowledge** for the [PROJECT_NAME] codebase - performance patterns, debug recipes, code conventions, and technical gotchas.
**For business logic and domain rules**, see `docs/domain/` directory.
**For current work notes**, use `docs/ai/TASKLOG.md`.
---
## 1) Code Conventions
[Add your project's conventions as you discover patterns]
### File Structure Requirements
- [Your conventions]
### Naming Conventions
- [Your conventions]
**Source**: AGENTS.md, team standards
---
## 2) Performance Patterns
[Add performance patterns as you discover them]
### Pattern Name
- **Pattern**: [Description]
- **Reason**: [Why this matters]
- **Example**: [Code example]
**Source**: [Investigation or observation]
---
## 3) Known Gotchas / Traps
[Document traps and gotchas as you encounter them]
### Issue Name
**Problem**: [What goes wrong]
**Cause**: [Why it happens]
**Fix**: [How to resolve]
**Source**: [Where you found this]
---
## 4) Debug Recipes
[Add step-by-step debug procedures as you develop them]
### Problem: [Issue Description]
**Symptoms**: [What you observe]
**Diagnosis**:
```bash
# Commands to investigate
```
Fix:
# Commands to resolve
Source: [Investigation doc or experience]
5) Integration Notes
[Document external service quirks and requirements]
[Service Name]
- [Key points about integration]
- [Rate limits, special requirements, etc.]
Source: [Documentation or observation]
6) Testing Conventions
[Document how to run and write tests]
Running Tests
# Your test commands
7) References
Domain Documentation
See docs/domain/ for business logic
Architecture Decisions
See docs/adr/ for structural changes
### Step 5: Create Verification Protocol (5 minutes)
Create `docs/ai/KNOWLEDGE_VERIFICATION.md`:
```markdown
# Knowledge Verification Protocol
**Purpose**: Ensure documentation stays accurate as code evolves.
**Schedule**: Monthly verification (first Monday of each month)
---
## Verification Process
### 1. Random Sample Check (15 minutes)
Pick 3-5 random source references from domain docs and verify accuracy:
```bash
# Get random sample of source references
grep -r "Source:" docs/domain/*.md | shuf -n 5
For each reference:
- Open the file at specified line number
- Verify behavior matches documented rule
- If changed: Update doc and mark with
<!-- Updated: YYYY-MM-DD --> - If verified: Add
<!-- Verified: YYYY-MM-DD -->if not present
2. Staleness Detection (10 minutes)
Check for potentially stale knowledge:
Code changes:
# Find recently changed files (last 30 days)
git log --since="30 days ago" --name-only --pretty=format: | sort -u | head -20
Action: For each changed file, verify corresponding docs are still accurate.
3. Confidence Marker Audit (5 minutes)
Review docs with these markers:
# Find hypotheses that need verification
grep -r "⚠️ HYPOTHESIS" docs/domain/*.md docs/ai/MEMORY.md
# Find items needing verification
grep -r "🔍 NEEDS VERIFICATION" docs/domain/*.md docs/ai/MEMORY.md
# Find time-sensitive info (check dates)
grep -r "📅 AS OF" docs/domain/*.md docs/ai/MEMORY.md
Action: Attempt to verify or update each finding.
Verification Checklist
Date: _
- Selected 3-5 random source references
- Verified each reference against current code
- Updated any stale documentation
- Checked recently changed files (last 30 days)
- Verified corresponding docs
- Audited confidence markers
- Added verification dates to checked docs
Found issues: _
Updated docs: _
Verification Log
| Date | Verifier | Docs Checked | Issues Found | Time Spent |
|---|---|---|---|---|
---
## The Four Knowledge Layers Explained
### Layer 1: AGENTS.md (Entry Point)
- **Purpose**: Foundational instructions for AI agents
- **Loaded by**: OpenCode/Cursor automatically at session start
- **Contains**: Protocols, conventions, mandatory reading list
- **Update frequency**: Rarely (foundational)
### Layer 2: docs/domain/*.md (Business Logic)
- **Purpose**: WHAT the system does (business rules, feature behavior)
- **Contains**: Entity relationships, state machines, workflows, edge cases
- **Update frequency**: Frequently (every time business logic discovered)
- **Example file**: `docs/domain/authentication.md`, `docs/domain/payments.md`
### Layer 3: docs/ai/MEMORY.md (Engineering Knowledge)
- **Purpose**: HOW to work with the code (debug recipes, patterns, gotchas)
- **Contains**: Performance tips, troubleshooting procedures, conventions
- **Update frequency**: Frequently (every time engineering insight discovered)
- **Single file**: All engineering knowledge in one place
### Layer 4: docs/adr/*.md (Architecture Decisions)
- **Purpose**: WHY structural choices were made (trade-offs, alternatives)
- **Contains**: Design decisions with rationale
- **Update frequency**: Rarely (only for significant architectural changes)
- **Format**: ADR template (Context, Decision, Consequences, Alternatives)
### Layer 5: docs/ai/TASKLOG.md (Work Scratchpad)
- **Purpose**: Current investigation/work in progress
- **Contains**: Hypotheses, debug commands, progress notes
- **Lifespan**: Temporary (created at task start, cleared at completion)
- **Single file**: Overwritten for each new task
---
## Templates for New Documentation
### Domain Doc Template
```markdown
# [Feature Name] Domain
## Overview
High-level description of what this feature does
## Entities
### [Model/Class Name]
- **Primary attributes**: [key fields]
- **Key associations**: [relationships]
- **States**: [if applicable]
**Source**: [file_path]
## Business Rules
### [Rule Category]
✅ **VERIFIED**: [Rule description]
**Edge cases**: [Exceptional scenarios]
**Source**: [file_path:line]
**Verified**: YYYY-MM-DD
## API Behavior
### [Integration Name]
[Describe API contracts, data formats]
**Source**: [file_path]
## Related Domains
- [domain1.md](./domain1.md) - [How they relate]
## References
- Source files: [List main files]
ADR Template
# ADR-NNN: [Decision Title]
**Status**: Accepted | Rejected | Superseded
**Date**: YYYY-MM-DD
## Context
What problem are we solving?
## Decision
What did we decide to do?
## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Trade-off 1]
- [Trade-off 2]
## Alternatives Considered
### Option 1: [Name]
**Pros**: [List]
**Cons**: [List]
**Why rejected**: [Reason]
## References
- [Related files or docs]
How It Works (Simple Explanation)
The Flow
1. User starts AI session
↓
2. OpenCode/Cursor loads AGENTS.md automatically
↓
3. AGENTS.md tells AI: "Read these knowledge files"
↓
4. AI reads:
- AGENTS.md (protocols)
- docs/ai/MEMORY.md (engineering tips)
- docs/domain/README.md (domain index)
- docs/domain/[relevant].md (business rules)
↓
5. AI outputs: "✅ Context Loaded" with key constraints
↓
6. User describes task
↓
7. AI works using existing knowledge (no repeated explanations)
↓
8. AI discovers new information during work
↓
9. AI immediately saves to correct layer (domain/MEMORY/TASKLOG)
↓
10. AI shows documentation diffs at end
↓
11. Knowledge persists for next session
Example Session
Without this system:
User: "Debug the payment processing issue"
AI: "Can you explain how payment processing works?"
User: [10 minutes of explanation]
With this system:
User: "Debug the payment processing issue"
AI: ✅ Context Loaded
Domain areas: payments
Key constraints:
- Stripe webhooks process async via background jobs
- Payment status updates trigger email notifications
- Refunds require admin approval
I'll check the debug recipe for webhook processing...
[AI immediately starts debugging with full context]
Time saved: 10-15 minutes per session
Customization for Your Project
Project-Specific Sections to Add
In AGENTS.md:
- Your build/test/lint commands
- Your code style guidelines
- Your git workflow
- Your deployment process
- Your tech stack specifics
In docs/domain/:
- Create one
.mdfile per major feature - Document your core entities
- Document your business workflows
- Document your integrations
In docs/ai/MEMORY.md:
- Your performance patterns
- Your common debug scenarios
- Your testing practices
- Your gotchas and traps
Language/Framework Adaptations
For Python projects:
- Add pytest commands
- Add Black/Flake8 conventions
- Add Django/Flask specifics
For JavaScript projects:
- Add npm/yarn commands
- Add ESLint/Prettier conventions
- Add React/Vue/Angular specifics
For Go projects:
- Add go test commands
- Add gofmt conventions
- Add module specifics
For Java projects:
- Add Maven/Gradle commands
- Add Checkstyle conventions
- Add Spring Boot specifics
Benefits You'll Get
Immediate (First Week)
- ✅ No repeated context explanations
- ✅ AI starts sessions with full knowledge
- ✅ Discoveries preserved automatically
Short-term (First Month)
- ✅ Debug recipes save troubleshooting time
- ✅ Business rules documented and verified
- ✅ Team members reference docs instead of asking
Long-term (3+ Months)
- ✅ Knowledge never gets lost
- ✅ Onboarding 50% faster
- ✅ Documentation stays current automatically
- ✅ Can build RAG/search tools on top
Metrics to Track
Time saved:
- Context explanation time per session (before: 10-15 min, after: 0 min)
- Debug time with recipes (measure before/after)
- Onboarding time for new developers
Documentation quality:
- Number of domain docs created
- Percentage of code with source references
- Verification completion rate (monthly)
Usage:
- Sessions using "✅ Context Loaded"
- Documentation updates per session
- Knowledge reuse (references to existing docs)
Troubleshooting
"AI doesn't read knowledge files"
Check:
- Is AGENTS.md in project root? (required)
- Does AGENTS.md have "Startup Behavior" section? (required)
- Did AI output "✅ Context Loaded"? (proof of reading)
Fix: Explicitly remind AI to follow AGENTS.md protocol
"Documentation getting stale"
Check:
- Are you running monthly verification? (required)
- Are confidence markers used? (helps identify uncertain knowledge)
- Are source references included? (enables verification)
Fix: Follow docs/ai/KNOWLEDGE_VERIFICATION.md schedule
"Too much documentation to maintain"
Check:
- Are you documenting during work? (automatic, not separate task)
- Are you using confidence markers? (focus on verified facts)
- Are you clearing TASKLOG.md? (don't keep temporary notes)
Fix: Documentation is part of work, not separate. Takes 2-3 min per session.
"Not sure what to document"
Use the Quick Decision Tree:
- Helps rebuild codebase? → Domain doc
- Debug/performance tip? → MEMORY.md
- Temporary note? → TASKLOG.md
- Structural decision? → ADR
When in doubt, ask: "Would I want to know this next month?" If yes, document it.
Success Criteria
You'll know it's working when:
✅ AI never asks "can you explain how X works?" for documented areas
✅ Debugging uses documented recipes instead of trial-and-error
✅ New team members read domain docs and get productive faster
✅ Important findings never get lost between sessions
✅ Documentation stays current without dedicated doc sprints
✅ Team references docs in code reviews and discussions
Next Steps After Setup
Day 1-7: Initial Population
- Document 2-3 core features in
docs/domain/ - Add 5-10 debug recipes to
docs/ai/MEMORY.md - Create 1-2 ADRs for major architectural choices
- Start using "✅ Context Loaded" checkpoint
Week 2-4: Habit Formation
- Document every discovery during work (automatic)
- Add confidence markers to all new knowledge
- Include source references consistently
- Review docs when debugging (use existing knowledge)
Month 2+: Maintenance Mode
- Run monthly verification (30 minutes)
- Watch for staleness and contradictions
- Promote hypotheses to verified as confirmed
- Build on existing docs instead of creating new ones
Resources
This Template
- Copy to your project root
- Customize project-specific sections
- Start documenting core features
- Follow protocols consistently
Additional Reading
FAQ
Q: How long does setup take?
A: 30 minutes to create structure, 2-3 hours to document initial core features
Q: Do I need to document everything immediately?
A: No. Start with 2-3 core features, grow organically as you work
Q: Can I use this with GitHub Copilot/Cursor/other tools?
A: Yes. The file structure works with any AI tool. Point AI to AGENTS.md.
Q: What if my team doesn't use AI?
A: Docs still valuable! Developers read domain docs for onboarding and reference
Q: How do I convince my team to adopt this?
A: Start with your own work, show time savings, share docs in code reviews
Q: Can I modify the structure?
A: Yes! This is a template. Adapt to your project's needs.
License
This template is free to use, modify, and distribute.
Attribution appreciated but not required.
Version: 1.0
Last Updated: 2024-02-11
Source: Adapted from ShowMojo implementation
Maintainer: Your team