Bootstrap a repository into Forgetful's knowledge base
Populates Forgetful knowledge base with comprehensive project context using a systematic Zettelkasten-inspired protocol.
/plugin marketplace add ScottRBK/forgetful-plugin/plugin install forgetful-plugin@forgetful-pluginsSystematically populate the Forgetful knowledge base with comprehensive project context using the Zettelkasten-inspired bootstrap protocol.
Transform an undocumented or lightly-documented codebase into a rich, searchable knowledge repository. Use this when:
$ARGUMENTS
Parse for:
execute_forgetful_tool("list_projects", {})
Search for the project. If found:
project_id (required for linking)Explore the codebase to determine:
Project Size:
Project Type:
execute_forgetful_tool("query_memory", {
"query": "<project-name> architecture overview",
"query_context": "Assessing existing knowledge base coverage for bootstrap",
"k": 10,
"include_links": true,
"project_ids": [<project_id if exists>]
})
Read key files:
Compare KB vs Codebase:
Report gap analysis before proceeding.
| Profile | Phase 1 | Phase 2 | Phase 2B | Phase 3 | Phase 4 | Phase 5 | Phase 6 | Total Memories |
|---|---|---|---|---|---|---|---|---|
| Small Simple | 3-5 | 3-5 | 3+ entities | 3-5 | 2-4 | 0-3 | 3+ artifacts | 15-27 |
| Small Complex | 5-7 | 5-8 | 5+ entities | 5-8 | 4-6 | 0-5 | 3-5 artifacts | 26-42 |
| Medium Standard | 5-10 | 10-15 | 8+ entities | 8-12 | 5-10 | 0-8 | 5-10 artifacts | 35-60 |
| Large | 8-12 | 15-20 | 12+ entities | 12-18 | 10-15 | 0-12 | 8-15 artifacts | 60-100 |
Note: Phase 5 shows "0-X" because decision memories are ONLY created when explicit documentation exists. Phase 2B and Phase 6 are MANDATORY with minimum counts.
CRITICAL: Do not proceed to the next phase until the current phase meets its minimum targets.
After each phase, report:
Phase [N] Complete:
- Created: [X] memories, [Y] entities, [Z] artifacts
- Minimum required: [targets from table above]
- Status: ✅ Met / ❌ Not met (explain gaps)
| Phase | Minimum Output | Gate Requirement |
|---|---|---|
| 0: Discovery | Gap analysis report | Report before proceeding |
| 1: Foundation | 5 memories + project entity | All 5 core memories created |
| 2: Architecture | Layer memories | 1 memory per identified layer |
| 2B: Entities | 3+ entities | Entity count met |
| 3: Patterns | 3+ pattern memories | Pattern count met |
| 6: Artifacts | 3+ code artifacts | Artifact count met |
| Phase | Condition | Skip Message |
|---|---|---|
| 4: Features | Features exist | "No distinct features beyond core architecture" |
| 5: Decisions | Explicit documentation exists | "No explicit decision documentation found" |
| 7: Documents | Content >400 words needed | "No long-form documentation needed" |
If project doesn't exist:
execute_forgetful_tool("create_project", {
"name": "owner/repo-name",
"description": "<2-3 paragraphs: problem solved, features, tech stack>",
"project_type": "development",
"repo_name": "owner/repo",
"notes": "<operational details: how to run, test, deploy>"
})
Project Overview (Importance: 10)
Technology Stack (Importance: 9)
Architecture Pattern (Importance: 10)
Development Setup (Importance: 8)
Testing Strategy (Importance: 8)
One memory per major architectural layer:
Template:
{
"title": "[Project] - [Layer] Layer Implementation",
"content": "Purpose, location, patterns used, interactions, design decisions",
"context": "Understanding this layer for [specific tasks]",
"keywords": ["layer-name", "pattern", "directory"],
"tags": ["architecture", "layer"],
"importance": 8,
"project_ids": [<project_id>]
}
Checkpoint: Report layer memories created before proceeding.
Purpose: Create a knowledge graph of project components, people, services, and their relationships.
THIS PHASE IS MANDATORY - Minimum 3 entities for any project.
Without entities, an agent cannot:
| Project Size | Minimum Entities | Recommended |
|---|---|---|
| Small | 3 | 3-5 |
| Medium | 5 | 8-12 |
| Large | 8 | 12-20 |
Core Services/Components (entity_type: "other", custom_type: "Service")
External Dependencies (entity_type: "other", custom_type: "ExternalService")
Key Abstractions (entity_type: "other", custom_type: "Pattern")
execute_forgetful_tool("create_entity", {
"name": "AuthService",
"entity_type": "other",
"custom_type": "Service",
"notes": "Handles JWT validation, user sessions, OAuth flows",
"aka": ["auth", "authentication"],
"tags": ["service", "security"],
"project_ids": [<project_id>]
})
After creating entities, map their relationships:
execute_forgetful_tool("create_entity_relationship", {
"source_entity_id": <auth_service_id>,
"target_entity_id": <user_repo_id>,
"relationship_type": "depends_on",
"strength": 0.9,
"notes": "AuthService requires UserRepository for credential lookup"
})
Relationship Types: uses, depends_on, extends, implements, connects_to, contains
Connect entities to their related memories:
execute_forgetful_tool("link_entity_to_memory", {
"entity_id": <entity_id>,
"memory_id": <architecture_memory_id>
})
Checkpoint:
Phase 2B Complete:
- Entities created: [count]
- Relationships mapped: [count]
- Entity-memory links: [count]
- Minimum required: 3 entities
- Status: ✅ Met / ❌ Not met
THIS PHASE IS MANDATORY - Minimum 3 pattern memories.
Search for these pattern types:
Dependency Injection / IoC
@inject, Depends(, container, providerError Handling
except, catch, Error, Exception, error middlewareDatabase Patterns
@transactional, session, commit, rollback, connection poolsAsync/Concurrency
async def, await, Promise, Future, lock, queueValidation
validate, schema, Pydantic, zod, @validatorCaching
@cache, redis, lru_cache, cache invalidationEvent/Message Patterns
emit, subscribe, publish, on_event, message queuesConfiguration
settings, config, env, .env, secrets management{
"title": "[Project] - Pattern: [Pattern Name]",
"content": "Where used, how implemented, key files, example usage",
"context": "Common pattern for [use case]",
"keywords": ["pattern", "specific-pattern-name"],
"tags": ["pattern", "implementation"],
"importance": 8,
"project_ids": [<project_id>]
}
Checkpoint:
Phase 3 Complete:
- Pattern memories created: [count]
- Pattern categories covered: [list]
- Minimum required: 3 memories
- Status: ✅ Met / ❌ Not met
User-Facing Features
Integration Features
Background/Scheduled Tasks
Core Business Logic
{
"title": "[Project] - Feature: [Feature Name]",
"content": "User perspective, technical approach, key files, data flow, dependencies",
"context": "Critical feature that [business value]",
"keywords": ["feature", "specific-feature-area"],
"tags": ["feature", "implementation"],
"importance": 8,
"project_ids": [<project_id>]
}
Checkpoint:
Phase 4 Complete:
- Feature memories created: [count]
- Major features documented: [list]
- Status: ✅ Complete / ⏭️ Skipped (no distinct features)
CRITICAL: This phase is CONDITIONAL. Only capture decisions that are EXPLICITLY documented.
✅ DO create decision memories for:
docs/adr/ or similar❌ DO NOT create decision memories for:
# ADR files
Glob: **/adr/**/*.md, **/decisions/**/*.md, **/docs/architecture*.md
# Decision markers in code
Grep: "DECISION:", "RATIONALE:", "WHY:", "We chose", "Reason:"
# README decision sections
Grep: "## Why", "## Design", "## Architecture Decisions", "## Rationale"
{
"title": "[Project] - Decision: [Topic]",
"content": "Decision: [what was decided]. Rationale: [QUOTE from docs]. Source: [file path]",
"context": "Documented decision from [source file]",
"keywords": ["decision", "topic-area"],
"tags": ["decision", "documented"],
"importance": 9,
"project_ids": [<project_id>]
}
Checkpoint:
Phase 5 Complete:
- Decision documentation found: Yes/No
- Decision memories created: [count]
- Sources: [list of files]
- Status: ✅ Complete / ⏭️ Skipped (no documentation found)
Purpose: Store reusable code patterns that enable an agent to understand HOW the codebase works, not just WHAT exists.
THIS PHASE IS MANDATORY - Minimum 3 artifacts for any project.
Without artifacts, an agent knows components exist but cannot:
| Project Size | Minimum Artifacts | Recommended |
|---|---|---|
| Small | 3 | 3-5 |
| Medium | 5 | 5-10 |
| Large | 8 | 8-15 |
execute_forgetful_tool("create_code_artifact", {
"title": "[Project] - [Pattern Name]",
"description": "What it does, when to use, key integration points",
"code": "<actual implementation code>",
"language": "python",
"tags": ["pattern-type", "layer"],
"project_id": <project_id>
})
After creating artifacts, link them to related memories:
execute_forgetful_tool("update_memory", {
"memory_id": <architecture_memory_id>,
"code_artifact_ids": [<artifact_id>]
})
Checkpoint:
Phase 6 Complete:
- Code artifacts created: [count]
- Categories covered: [list]
- Minimum required: 3 artifacts
- Status: ✅ Met / ❌ Not met
For long-form content (>400 words), create documents with atomic memory entry points:
execute_forgetful_tool("create_document", {
"title": "[Project] - [Document Topic]",
"description": "Overview and purpose",
"content": "<full documentation>",
"document_type": "markdown",
"tags": ["documentation", "topic-area"],
"project_id": <project_id>
})
After creating a document:
document_idsCheckpoint:
Phase 7 Complete:
- Documents created: [count]
- Entry point memories: [count]
- Status: ✅ Complete / ⏭️ Skipped (not needed)
| Phase | Minimum Output | Gate Requirement |
|---|---|---|
| 0: Discovery | Gap analysis report | Report before proceeding |
| 1: Foundation | 5 memories + project | All 5 core memories created |
| 2: Architecture | Layer memories | 1 per identified layer |
| 2B: Entities | 3+ entities | Entity count met |
| 3: Patterns | 3+ memories | Pattern count met |
| 6: Artifacts | 3+ artifacts | Artifact count met |
| Phase | Condition to Run | Skip Message |
|---|---|---|
| 4: Features | Distinct features exist | "No distinct features beyond core architecture" |
| 5: Decisions | Explicit docs exist | "No explicit decision documentation found" |
| 7: Documents | Long-form needed | "No long-form documentation needed" |
After completion, test with validation queries:
# Test 1: Architecture understanding
execute_forgetful_tool("query_memory", {
"query": "How is the codebase architected?",
"query_context": "Testing bootstrap coverage",
"project_ids": [<project_id>]
})
# Test 2: Implementation patterns
execute_forgetful_tool("query_memory", {
"query": "How do I add a new API endpoint?",
"query_context": "Testing bootstrap coverage",
"project_ids": [<project_id>]
})
# Test 3: Entity graph
execute_forgetful_tool("list_entities", {
"project_ids": [<project_id>]
})
If searches return poor results, create additional memories in those areas.
When encoding is complete, provide a summary in this format:
# [Project] Encoding Complete
## Artifacts Created
| Type | Count | Minimum | Status |
|------|-------|---------|--------|
| Memories | [X] | [per profile] | ✅/❌ |
| Entities | [Y] | 3+ | ✅/❌ |
| Relationships | [Z] | - | - |
| Code Artifacts | [W] | 3+ | ✅/❌ |
| Documents | [V] | 0 | ✅ |
## Phase Completion
| Phase | Status | Output |
|-------|--------|--------|
| 0: Discovery | ✅ | Gap analysis |
| 1: Foundation | ✅ | [X] memories |
| 2: Architecture | ✅ | [X] memories |
| 2B: Entities | ✅/❌ | [X] entities |
| 3: Patterns | ✅ | [X] memories |
| 4: Features | ✅/⏭️ | [X] memories |
| 5: Decisions | ✅/⏭️ | [X] memories |
| 6: Artifacts | ✅/❌ | [X] artifacts |
| 7: Documents | ✅/⏭️ | [X] documents |
## Entity Graph Summary
Created entities:
- [Entity 1]: [type] - [description]
- [Entity 2]: [type] - [description]
- ...
Relationships:
- [Entity A] → [relationship] → [Entity B]
- ...
## Validation Queries Tested
- [Query 1]: [result quality]
- [Query 2]: [result quality]
- [Query 3]: [result quality]
After each phase, report:
Proceed automatically to the next phase once the checkpoint is met. Do not wait for user confirmation.