Agent Knowledge Repository

This is the knowledge/memory template for an autonomous agent. Clone this for each project.

⚠️ IMPORTANT: This is a READ-ONLY template repository.

• DO NOT commit project-specific data to this repository
• This template is CLONED into each project's .knowledge/ directory
• All agent commits go to the PROJECT repository, not here
• The .git directory is removed after cloning to prevent pushback

How It Works

The agent reads its context from JSON files, does work, then updates those files to track progress. Everything is committed to Git for full history.

Agent starts
    ↓
Reads context/*.json  →  Understands project, objectives, current task
    ↓
Does the work  →  Builds features, fixes bugs
    ↓
Updates .knowledge/  →  Records what it did, decisions made
    ↓
Commits & pushes  →  State persisted for next run
    ↓
Agent ends (or loops)

Directory Structure

.knowledge/
├── context/
│   ├── project.json      # What is this project?
│   ├── objectives.json   # What are we trying to achieve?
│   └── current.json      # What are we doing right now?
│
├── work/
│   ├── backlog.json      # Future work items
│   ├── in-progress.json  # Currently being worked on
│   └── completed.json    # Recently completed (changelog feed)
│
├── decisions/
│   ├── log.jsonl         # Append-only decision log
│   └── rationale/        # Detailed reasoning for major decisions
│
├── memory/
│   ├── learnings.json    # Patterns and insights discovered
│   ├── mistakes.json     # What went wrong (to avoid repeating)
│   └── recent.json       # Recent session context
│
├── metrics/
│   ├── latest.json       # Current health metrics
│   └── history/          # Historical snapshots
│
├── plans/
│   ├── current.json      # Active strategic plan
│   └── archive/          # Past plans
│
└── schemas/              # JSON schemas for validation

Build-in-Public Integration

This knowledge structure is designed to power the Build in Public dashboard in the SaaS Boilerplate. When you use the boilerplate, these files are exposed via API routes:

Knowledge File	API Route	Dashboard Component
context/current.json	/api/knowledge/current	CurrentFocus widget
work/in-progress.json	/api/knowledge/tasks?status=in-progress	TaskBoard
work/completed.json	/api/knowledge/changelog	Changelog page
decisions/log.jsonl	/api/knowledge/decisions	DecisionFeed
memory/learnings.json	/api/knowledge/learnings	LearningsView
metrics/latest.json	/api/knowledge/metrics	MetricsPanel

This creates transparency for users and accountability for the agent.

Key Files

context/current.json - Current State

What the agent should focus on right now:

{
  "version": "1.0",
  "updated_at": "2024-12-03T10:00:00Z",
  
  "focus": {
    "current_task": "Build user settings page",
    "blocked_on": null,
    "waiting_for": null
  },
  
  "project_state": {
    "phase": "building",
    "health": "healthy",
    "last_deploy": "2024-12-02T15:30:00Z",
    "active_users": 42
  },
  
  "priorities": [
    "Complete settings feature",
    "Add email notifications",
    "Polish onboarding flow"
  ],
  
  "last_completed": "Implemented user authentication",
  "last_completed_at": "2024-12-02T14:00:00Z",
  
  "next_actions": [
    "Create SettingsForm component",
    "Add settings API route",
    "Wire up to page"
  ],
  
  "session_notes": [
    "Settings will need to sync with Clerk metadata"
  ]
}

context/project.json - Project Definition

What this project is:

{
  "version": "1.0",
  "name": "RSSFlow",
  "description": "RSS feed aggregator with AI summarization",
  "status": "building",
  
  "tech_stack": {
    "framework": "Next.js 15 (from SaaS Boilerplate)",
    "language": "TypeScript",
    "auth": "Clerk",
    "database": "MongoDB",
    "styling": "Tailwind CSS + shadcn/ui",
    "payments": "Stripe via Clerk Billing"
  },
  
  "features": [
    {"name": "Feed Management", "status": "done", "priority": "high"},
    {"name": "AI Summaries", "status": "building", "priority": "high"},
    {"name": "Notifications", "status": "planned", "priority": "medium"}
  ],
  
  "boilerplate_version": "1.0",
  "created_at": "2024-12-01"
}

work/backlog.json - Work Items

Tasks waiting to be worked on:

{
  "version": "1.0",
  "updated_at": "2024-12-03T10:00:00Z",
  
  "items": [
    {
      "id": "feature-notifications",
      "type": "feature",
      "title": "Email notifications for new articles",
      "description": "Send daily digest of new articles in feeds",
      "priority": 1,
      "estimated_effort": "medium",
      "dependencies": ["feature-settings"],
      "implementation_steps": [
        "Add notification preferences to settings",
        "Create digest email template",
        "Add cron job for daily send"
      ],
      "acceptance_criteria": [
        "User can enable/disable notifications",
        "Digest sent at configured time",
        "Unsubscribe link works"
      ],
      "created_at": "2024-12-02T10:00:00Z"
    }
  ]
}

decisions/log.jsonl - Decision Log

Append-only log of decisions made:

{"timestamp": "2024-12-01T10:00:00Z", "type": "strategic", "decision": "Using SaaS Boilerplate as foundation", "reasoning": "Provides auth, payments, and patterns out of the box", "confidence": 0.95}
{"timestamp": "2024-12-02T14:30:00Z", "type": "tactical", "decision": "Store feed items in MongoDB instead of external service", "reasoning": "Simpler architecture, sufficient scale for MVP", "confidence": 0.85}
{"timestamp": "2024-12-03T09:00:00Z", "type": "operational", "decision": "Add rate limiting to feed refresh API", "reasoning": "Prevent abuse and control external API costs", "confidence": 0.9}

metrics/latest.json - Health Metrics

Current state of the product:

{
  "version": "1.0",
  "updated_at": "2024-12-03T10:00:00Z",
  
  "users": {
    "total": 150,
    "active_7d": 42,
    "new_7d": 12
  },
  
  "revenue": {
    "mrr": 270,
    "arr": 3240
  },
  
  "health": {
    "uptime_percent": 99.9,
    "error_rate": 0.02,
    "avg_response_ms": 150
  },
  
  "development": {
    "tasks_completed_7d": 5,
    "decisions_made_7d": 8,
    "commits_7d": 23
  }
}

Usage

For a New Project

1. Initialize the SaaS Boilerplate as your project
2. Copy this template into .knowledge/ directory within the project
3. Remove the .git directory from .knowledge/ (critical!)
4. Fill in context/project.json with your project details
5. Set initial objectives in context/objectives.json
6. Run the agent

🔴 Critical: The .git directory must be removed from .knowledge/ after copying. The agent commits to the project's git repository, not the template.

For the Agent

The agent:

1. Reads all context files to build understanding
2. Picks task from work/backlog.json or context/current.json
3. Executes the work following boilerplate patterns
4. Updates context files with progress
5. Logs decisions in decisions/log.jsonl
6. Moves completed items to work/completed.json
7. Commits changes to the PROJECT repository (not the template)

When to Update Each File

File	Update When
context/current.json	Starting/finishing tasks, status changes
context/project.json	Feature status changes, tech stack changes
work/backlog.json	New tasks identified, priorities change
work/in-progress.json	Starting/pausing work
work/completed.json	Finishing work (powers changelog)
decisions/log.jsonl	Making any significant decision
memory/learnings.json	Discovering patterns or best practices
memory/mistakes.json	Something went wrong to avoid repeating
metrics/latest.json	After deploys, weekly for stats

Decision Types

Type	When to Use
strategic	Architecture, tech choices, major features
tactical	Implementation approach, library choices
operational	Configuration, deployment, fixes

Work Item Types

Type	Description
feature	New functionality
bug	Something broken
improvement	Enhancement to existing feature
chore	Maintenance, cleanup, updates

Effort Estimation

Effort	Typical Time	Example
tiny	< 30 min	Add a field
small	30 min - 2 hr	New validation schema
medium	2-8 hr	Full feature slice
large	1-3 days	New entity with CRUD
huge	3+ days	Major refactor

Design Principles

• JSON for structured data — Easy for agent to parse and update
• Git for persistence — Full history, survives restarts
• Agent-writable — Agent updates its own state
• Human-readable — You can inspect and modify state
• Dashboard-ready — Structure matches Build in Public UI

Schema Validation

The schemas/ directory contains JSON schemas for validating knowledge files. Use these when building tooling or ensuring data integrity.

---

Part of the Comet Apps ecosystem — Autonomous AI agents building and operating SaaS products.