Napkin

Napkin is a development skill for maintaining per-repository runbooks that serve as persistent agent memory, covering mistake documentation, knowledge curation, and continuous learning from failures

What Is This?

Overview

Napkin is a lightweight system for maintaining a living document within each repository that captures lessons learned, common mistakes, and solutions discovered during development. Rather than letting knowledge scatter across chat logs, emails, and forgotten issues, Napkin creates a centralized runbook that grows with your project. It is designed to help both AI agents and developers quickly reference what has gone wrong before and how to fix it, reducing the time spent rediscovering solutions.

The tool integrates directly into your repository workflow, making it easy to append new learnings whenever mistakes occur or solutions are discovered. This creates a searchable knowledge base that improves over time, reducing repeated errors and accelerating problem-solving for both humans and AI assistants working on the codebase. Napkin entries can be as simple as a single line or as detailed as a multi-step solution, and the system encourages frequent, incremental updates.

Who Should Use This

Teams that work with AI agents, developers managing complex codebases, and projects where repeated mistakes waste time should adopt Napkin. It's particularly valuable for teams using LLM-based tools that benefit from contextual failure documentation. Solo developers can also benefit by building a personal memory bank of project-specific issues and solutions, making future maintenance and onboarding easier.

Why Use It?

Problems It Solves

AI agents and developers often repeat the same mistakes because context is lost between sessions or across team members. Napkin solves this by maintaining a persistent, searchable record of what has failed and why. Instead of rediscovering solutions, you reference the napkin. This dramatically reduces debugging time and prevents regression into previously solved problems. It also helps teams avoid knowledge silos, ensuring that critical troubleshooting information is accessible to everyone.

Core Highlights

Napkin creates a per-repository runbook that captures mistakes and solutions in one searchable location. The system integrates seamlessly into existing workflows without requiring complex setup or maintenance overhead. AI agents can reference the napkin to avoid repeating known failures and provide better context-aware assistance. The document grows continuously as new learnings are added, becoming more valuable over time. Napkin’s simplicity encourages regular use, and its integration with version control ensures that knowledge is preserved alongside code changes.

How to Use It?

Basic Usage

Initialize napkin in your repository and start documenting failures:

napkin init
napkin add "Database connection timeout on cold starts"
napkin add "Solution: Implement connection pooling with 30s timeout"
napkin search "timeout"
napkin list

Each entry should clearly state the problem and, if possible, the solution or workaround. Over time, this builds a comprehensive log of issues and fixes.

Real-World Examples

Document a common build failure and its resolution:

napkin add "Build fails with 'module not found' after npm update"
napkin add "Fix: Run npm ci instead of npm install in CI pipeline"
napkin add "Root cause: package-lock.json wasn't committed"

Capture a deployment issue and recovery steps:

napkin add "Production deployment hangs on database migration"
napkin add "Recovery: Rollback to previous version, run migration locally first"
napkin add "Prevention: Always test migrations in staging environment"

You can also use Napkin to record environment-specific quirks, such as OS-specific bugs or configuration requirements, ensuring that future team members do not repeat the same troubleshooting steps.

Advanced Tips

Use consistent formatting and tags when adding entries so the napkin remains searchable and organized as it grows. For example, prefix entries with tags like [build], [deploy], or [config]. Reference the napkin during code reviews and onboarding to help new team members understand the project's history of failures and solutions. Periodically review and prune outdated entries to keep the napkin relevant.

When to Use It?

Use Cases

Use Napkin when onboarding new developers to quickly familiarize them with known pitfalls and solutions specific to your codebase. Integrate it into AI agent workflows to provide context about previous failures and prevent repeated mistakes. Reference it during debugging sessions to check if a problem has been encountered and solved before. Use it to document environment-specific issues, configuration gotchas, and deployment procedures that are easy to forget. Napkin is also useful during incident postmortems to ensure lessons learned are captured and shared.

Related Topics

Napkin complements version control systems like Git, documentation tools like Markdown wikis, and AI agent frameworks that benefit from contextual knowledge bases. It can be used alongside automated monitoring and alerting systems to provide human-readable context for recurring issues.

Important Notes

While Napkin offers a simple and effective way to capture persistent knowledge within each repository, it relies on consistent usage and integration with your team's workflow. Proper setup and disciplined documentation practices are essential to maximize its benefits. Be aware of its requirements and limitations to ensure it fits your development environment and knowledge-sharing needs.

Requirements

• Access to the target repository with write permissions to store and update the napkin file
• Installation of the Napkin CLI tool in your development environment
• Basic familiarity with command-line operations
• Optional: Integration with version control systems like Git for change tracking

Usage Recommendations

• Regularly update the napkin after encountering new issues or solutions to keep information current
• Use clear, concise language and consistent tagging for easy searching and filtering
• Review and clean up outdated or irrelevant entries periodically to maintain relevance
• Reference the napkin during onboarding, code reviews, and incident analysis to reinforce its value
• Encourage all team members, including AI agents, to contribute to and consult the napkin

Limitations

• Napkin does not automatically detect or log issues; manual entry is required
• It is not a replacement for comprehensive documentation or automated monitoring tools
• Entries can become disorganized or outdated without regular maintenance
• The napkin is only as useful as the quality and consistency of its content