Developer Project Memory

---
name: Developer Project Memory
description: 'A ready-made knowledge base for your codebase. Architecture, conventions,
  decisions, runbooks. Claude and ChatGPT read it before they write a line.

  '
tags:
- decision
- runbook
- convention
- open-question
containers:
- name: Developer Project Memory
  description: The durable context around your codebase. Your AI reads it before it
    answers.
  llm_instructions: |
    This is the project memory for one codebase. It stores the context that does not live in the repo itself: architecture, conventions, decisions, runbooks, open questions.
    - Before answering anything about how the system works or how the team writes code, search this folder first. Cite the exact note you used.
    - Never invent conventions, decision rationales, or runbook steps. If a folder does not contain the answer, say so plainly and ask the user.
    - Treat the Conventions and Decisions folders as binding. If a draft contradicts them, flag it instead of silently rewriting.
    - When the user resolves an open question or makes a new decision in conversation, suggest saving it back into the right folder so the memory compounds.
    - This template does not replace a code editor or repo indexer. It is the layer around the code, not the code itself.
  children:
  - name: Architecture
    description: Stack overview, service boundaries, data flow, system diagrams.
    llm_instructions: |
      Use this folder for how the system is shaped.
      - When asked how the system works, search this folder first and quote the exact note.
      - Keep notes scoped: one note per service, one per major data model, one per cross-cutting concern.
      - Update notes in place when the architecture changes. Do not append to the bottom in a journal style.
      - If the user describes new architecture in conversation, suggest saving it here.
  - name: Conventions
    description: Naming, error handling, test patterns, PR style. How this team writes
      code.
    llm_instructions: |
      Use this folder for the rules of how the team writes code.
      - When writing or reviewing code, read this folder first and follow what is here exactly.
      - If a draft contradicts a convention, flag the conflict. Do not silently rewrite either side.
      - When the user describes a coding rule in conversation that is not yet captured, suggest saving it here.
      - Tag every note with "convention".
  - name: Decisions
    description: Why you picked Postgres. Why you dropped Redis. What you tried and
      rejected.
    llm_instructions: |
      Use this folder as a decision log.
      - When asked "why do we do X this way", search this folder first and quote the matching note.
      - Structure each decision note with: Context, Options considered, Decision, Tradeoffs accepted, Date.
      - Never modify a past decision silently. If a new decision supersedes an old one, create a new note and link the two.
      - Tag every note with "decision".
  - name: Runbooks
    description: Deploy steps, rollback procedures, incident playbooks.
    llm_instructions: |
      Use this folder for procedural steps the AI can read and follow.
      - When asked about deploys, rollbacks, or incidents, search this folder first and follow the steps exactly. Do not improvise.
      - Each runbook should be a numbered list of executable steps. Keep prose to the minimum needed for context.
      - When a step fails or the procedure changes, suggest updating the runbook before moving on.
      - Tag every note with "runbook".
  - name: Open Questions
    description: Things you are still figuring out, so the AI does not guess.
    llm_instructions: |
      Use this folder for unresolved questions.
      - When asked something open, check here first and say so plainly if it is unresolved.
      - Keep question notes short: the question, why it matters, partial answers, links to relevant decisions or architecture notes.
      - When a question is resolved, move the answer into Decisions or Architecture, then either delete the question note or tag it "resolved".
      - Tag every note with "open-question".
  notes:
  - title: Architecture Overview
    body: |
      A skeleton of how the system is shaped. Replace each section with your real material.

      ## Stack
      - Language and framework:
      - Database:
      - Queue / background jobs:
      - Cache:
      - Hosting:

      ## Services
      - Service A:
      - Service B:

      ## Data flow
      Describe how a request moves through the system end to end.

      ## Cross-cutting concerns
      - Auth:
      - Logging and observability:
      - Error tracking:

      This is a starter note. Replace it with your real architecture.
    tags:
    - convention
    container_path: Developer Project Memory > Architecture
  - title: Coding Conventions Checklist
    body: |
      The rules of how this team writes code. Replace with your real conventions.

      ## Naming
      - Functions:
      - Variables:
      - Files and modules:

      ## Error handling
      - Default pattern:
      - When to retry:
      - When to surface to the user:

      ## Testing
      - What we test:
      - What we do not test:
      - Test naming and structure:

      ## Pull requests
      - PR size limit:
      - Required review:
      - Commit message style:

      This is a starter note. Replace it with your real conventions.
    tags:
    - convention
    container_path: Developer Project Memory > Conventions
  - title: Decision Record Example
    body: |
      One past decision, captured so future you and the AI can both read it.

      ## Context
      We needed a primary datastore for the platform.

      ## Options considered
      1. Postgres
      2. MySQL
      3. A managed document database

      ## Decision
      Postgres.

      ## Tradeoffs accepted
      - More operational ownership in exchange for relational guarantees.
      - Slightly more setup work up front in exchange for fewer surprises later.

      ## Date
      Replace with the real date when you adopt this template.

      This is a starter note. Replace it with one of your real decisions.
    tags:
    - decision
    container_path: Developer Project Memory > Decisions
  - title: Deploy Runbook Example
    body: |
      A linear set of steps for a typical deploy. Replace with your real procedure.

      1. Confirm the main branch is green on CI.
      2. Tag the release commit.
      3. Run the database migration in a dry run.
      4. Run the migration for real.
      5. Deploy the new image.
      6. Watch error rates for 10 minutes.
      7. If the error rate spikes, follow the Rollback runbook.

      ## Rollback
      1. Re-deploy the previous image tag.
      2. Revert the migration if it changed schema.
      3. Post to the incident channel with what changed.

      This is a starter note. Replace it with your real deploy steps.
    tags:
    - runbook
    container_path: Developer Project Memory > Runbooks
  - title: Open Question Example
    body: |
      One unresolved question with what is known and what is not.

      ## Question
      Should background jobs run in a separate process or inside the web service?

      ## Why it matters
      Affects deploy strategy, scaling, and observability.

      ## What we know
      - Current load fits comfortably in one process.
      - We expect traffic to roughly triple in the next year.

      ## What we do not know
      - Whether the workload mix will stay the same.
      - Whether the operational cost of a second process is worth it now.

      This is a starter note. Replace it with a real open question.
    tags:
    - open-question
    container_path: Developer Project Memory > Open Questions