mema-kit 1.0.0

package/README.md

@@ -0,0 +1,105 @@
+# mema-kit
+
+Memory protocol kit for Claude Code skills. Give any skill persistent, curated memory across sessions.
+
+**What it does:** A `.mema/` directory in your project stores architecture decisions, requirements, lessons learned, and reusable patterns as curated markdown. Skills automatically load relevant context at the start of each session and save curated knowledge when done.
+
+**Key differentiator:** The memory protocol (AUTO-LOAD → WORK → AUTO-SAVE & CURATE → AUTO-INDEX) is a reusable pattern. Any skill you build can plug into it — not just the two that ship with mema-kit.
+
+## Quick Start
+
+```bash
+# 1. Install skills into your project
+npx mema-kit
+
+# 2. Open Claude Code and bootstrap memory
+claude
+> /onboard
+```
+
+`/onboard` scans your project, creates the `.mema/` memory structure, populates initial architecture and requirements docs, and configures CLAUDE.md and `.gitignore`.
+
+## Built-in Skills
+
+| Command | Purpose |
+|---------|---------|
+| `/onboard` | Bootstrap memory for a project — scans codebase, creates `.mema/`, populates initial knowledge |
+| `/create-skill` | Generate a new memory-aware skill with the correct lifecycle phases |
+
+## How Memory Works
+
+mema-kit uses a `.mema/` directory in your project to persist knowledge between sessions:
+
+```
+.mema/
+├── index.md             # Memory map — agent reads this first
+├── project-memory/      # Architecture, requirements, decisions
+│   └── decisions/       # Individual decision records with reasoning
+├── task-memory/         # Per-task context, plans, active work
+├── agent-memory/        # Lessons learned, reusable patterns
+└── archive/             # Completed task memories
+```
+
+- **Auto-load**: Skills read `index.md` and load only the files relevant to the current task.
+- **Auto-save**: After work, the agent curates findings into the right memory files.
+- **Auto-prune**: Noise is removed; only actionable knowledge is kept.
+- **Self-healing**: If `index.md` gets out of sync, the next skill rebuilds it from the directory structure.
+
+Memory is just markdown. Open any file to see what the agent knows. Edit directly if something's wrong.
+
+## The Memory Protocol
+
+Every memory-aware skill follows four phases:
+
+1. **AUTO-LOAD** — Read `index.md`, decide what's relevant, load only those files
+2. **WORK** — Execute the skill's core purpose with loaded context
+3. **AUTO-SAVE & CURATE** — For each piece of knowledge, decide: ADD / UPDATE / DELETE / NOOP
+4. **AUTO-INDEX** — Update `index.md` to reflect all changes
+
+The protocol is defined in `_memory-protocol.md` and shared across all skills (never duplicated). See [docs/guide.md](docs/guide.md) for the full protocol reference.
+
+## Building Your Own Skills
+
+Use `/create-skill` to generate memory-aware skills:
+
+```
+> /create-skill
+
+Skill name: review
+Purpose: Review code changes for quality and consistency
+Complexity: standard
+```
+
+This creates `.claude/skills/review/SKILL.md` with the full 4-phase memory lifecycle wired in. Three complexity levels are available:
+
+- **Simple** (3 phases) — Read-only skills like code review, linting
+- **Standard** (4 phases) — Most skills that read and write memory
+- **Advanced** (4 phases + task management) — Multi-step workflows with archiving
+
+See [docs/guide.md](docs/guide.md) for a complete worked example.
+
+## Updating
+
+```bash
+npx mema-kit --update
+```
+
+Updates skill files only. Never touches `.mema/`, CLAUDE.md, or `.gitignore`.
+
+## Requirements
+
+- Node.js >= 16.7.0
+- [Claude Code](https://claude.ai/code)
+
+## Documentation
+
+See [docs/guide.md](docs/guide.md) for the full usage guide with worked examples and protocol reference.
+
+## Links
+
+- [npm package](https://www.npmjs.com/package/mema-kit)
+- [GitHub repository](https://github.com/simonv15/mema-kit)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const VERSION = require('../package.json').version;
+const VERSION_COMMENT = `<!-- mema-kit v${VERSION} -->`;
+
+// Paths
+const packageRoot = path.resolve(__dirname, '..');
+const skillsSource = path.join(packageRoot, 'skills');
+const targetDir = path.join(process.cwd(), '.claude', 'skills');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const isUpdate = args.includes('--update');
+const isHelp = args.includes('--help') || args.includes('-h');
+
+if (isHelp) {
+  printHelp();
+  process.exit(0);
+}
+
+if (isUpdate) {
+  runUpdate();
+} else {
+  runInstall();
+}
+
+function runInstall() {
+  // Check if skills already exist
+  if (fs.existsSync(targetDir)) {
+    const hasSkills = fs.readdirSync(targetDir).some(f => f.endsWith('.md') || fs.statSync(path.join(targetDir, f)).isDirectory());
+    if (hasSkills) {
+      console.log('⚠  mema-kit skills already exist in .claude/skills/');
+      console.log('   Use --update to replace with the latest version.');
+      console.log('   Or delete .claude/skills/ and run again for a fresh install.');
+      process.exit(1);
+    }
+  }
+
+  // Create target directory
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  // Copy all skills
+  copySkills();
+
+  console.log('✓ mema-kit skills installed to .claude/skills/');
+  console.log('');
+  console.log('Next step: Open your project in Claude Code and run /onboard');
+  console.log('');
+  console.log('  claude');
+  console.log('  > /onboard');
+  console.log('');
+}
+
+function runUpdate() {
+  if (!fs.existsSync(targetDir)) {
+    console.log('⚠  No .claude/skills/ directory found.');
+    console.log('   Run npx mema-kit (without --update) for a fresh install.');
+    process.exit(1);
+  }
+
+  // Check current version
+  const protocolPath = path.join(targetDir, '_memory-protocol.md');
+  if (fs.existsSync(protocolPath)) {
+    const content = fs.readFileSync(protocolPath, 'utf8');
+    const versionMatch = content.match(/<!-- mema-kit v([\d.]+) -->/);
+    if (versionMatch && versionMatch[1] === VERSION) {
+      console.log(`✓ mema-kit skills are already at v${VERSION}. No update needed.`);
+      process.exit(0);
+    }
+    if (versionMatch) {
+      console.log(`Updating mema-kit skills from v${versionMatch[1]} to v${VERSION}...`);
+    }
+  }
+
+  // Copy (overwrite) all skills
+  copySkills();
+
+  console.log(`✓ mema-kit skills updated to v${VERSION}`);
+  console.log('');
+  console.log('  .mema/ and CLAUDE.md were not modified.');
+  console.log('');
+}
+
+function copySkills() {
+  const entries = fs.readdirSync(skillsSource, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(skillsSource, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      // Skill directory (e.g., onboard/)
+      fs.mkdirSync(targetPath, { recursive: true });
+      const files = fs.readdirSync(sourcePath);
+      for (const file of files) {
+        const content = fs.readFileSync(path.join(sourcePath, file), 'utf8');
+        fs.writeFileSync(path.join(targetPath, file), addVersionComment(content));
+      }
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      // Standalone file (e.g., _memory-protocol.md)
+      const content = fs.readFileSync(sourcePath, 'utf8');
+      fs.writeFileSync(targetPath, addVersionComment(content));
+    }
+  }
+}
+
+function addVersionComment(content) {
+  // Remove any existing version comment
+  const cleaned = content.replace(/<!-- mema-kit v[\d.]+ -->\n?/, '');
+  // Add current version at the end
+  return cleaned.trimEnd() + '\n\n' + VERSION_COMMENT + '\n';
+}
+
+function printHelp() {
+  console.log(`
+mema-kit v${VERSION} — Memory protocol kit for Claude Code skills
+
+Usage:
+  npx mema-kit            Install skills to .claude/skills/
+  npx mema-kit --update   Update skills to the latest version
+  npx mema-kit --help     Show this help message
+
+After installing, open your project in Claude Code and run /onboard.
+
+Learn more: https://github.com/simonv15/mema-kit
+  `.trim());
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "mema-kit",
+  "version": "1.0.0",
+  "description": "Reusable memory protocol kit for Claude Code skills",
+  "bin": {
+    "mema-kit": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "templates/"
+  ],
+  "keywords": [
+    "claude-code",
+    "ai-memory",
+    "claude-skills",
+    "memory-protocol",
+    "agent-memory"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simonv15/mema-kit.git"
+  },
+  "engines": {
+    "node": ">=16.7.0"
+  }
+}

package/skills/_memory-protocol.md

@@ -0,0 +1,146 @@
+# Memory Protocol
+
+This document defines how you manage memory in `.mema/`. Every skill that reads or writes memory must follow these rules.
+
+## The Memory Lifecycle
+
+Every skill execution follows four phases:
+
+### Phase 1: AUTO-LOAD
+1. Read `.mema/index.md` to understand current project state
+2. If `index.md` is missing or empty, run the **Rebuild Procedure** (see below)
+3. Based on the user's request, decide which memory files are relevant
+4. Read only the relevant files — do NOT load everything
+
+**How to decide relevance:** Scan each index entry's one-line summary. If it relates to the user's current topic, technology, or task — load it. When in doubt, load it. When clearly unrelated, skip it.
+
+### Phase 2: WORK
+Execute the skill's core purpose (research, planning, test generation, implementation) with the loaded context.
+
+### Phase 3: AUTO-SAVE & CURATE
+For every piece of knowledge produced during this session, decide one of four actions:
+
+**ADD** — Save new knowledge that doesn't exist yet
+- A new decision with reasoning
+- A new exploration finding worth preserving
+- A new lesson learned from implementation
+- A new pattern discovered for reuse
+
+**UPDATE** — Modify existing knowledge that has changed
+- A decision's reasoning was refined
+- Architecture changed due to new requirements
+- A plan step was adjusted during implementation
+- A lesson gained a new example
+
+**DELETE** — Remove knowledge that is wrong, superseded, or irrelevant
+- Dead-end exploration (evaluated and rejected — no future value)
+- Superseded decisions (old decision replaced by new one — keep the new one only)
+- Redundant information (already captured in a more complete file)
+- Temporary notes that served their purpose
+
+**NOOP** — Leave unchanged (the memory is still accurate and relevant)
+- Most memories should be NOOP on any given skill execution
+- Only act (ADD/UPDATE/DELETE) when there's a clear reason
+
+### Phase 4: AUTO-INDEX
+Update `.mema/index.md` to reflect all changes made in Phase 3. This is **mandatory** — never skip it.
+
+## What to Save vs. What to Prune
+
+### SAVE (curated knowledge worth preserving):
+- Decisions with reasoning: "Chose Fastify over Express because: 2x faster benchmarks, built-in schema validation, better TypeScript support"
+- Architecture and design patterns: "API follows controller → service → repository layers"
+- Requirements and constraints: "Must support 100 concurrent users, PostgreSQL is required by client"
+- Lessons from failures: "Drizzle ORM needs explicit type casting for PostgreSQL enums — spent 30 min debugging this"
+- Reusable patterns: "Fastify route registration pattern: define schema, write handler, register in app.ts"
+
+### PRUNE (noise that wastes future context):
+- Conversational back-and-forth that led to a conclusion (keep the conclusion, prune the discussion)
+- Dead-end explorations with no useful outcome (evaluated MongoDB, doesn't fit — delete the comparison notes)
+- Temporary debugging context (fixed the bug, no recurring lesson — delete)
+- Verbose explanations when a concise summary exists (condense, don't hoard)
+- Information already captured elsewhere (don't duplicate across files)
+
+## Per-File-Type Curation Rules
+
+### decision.md — Conservative curation
+- **Rarely delete.** Decisions are historical record. Even reversed decisions teach future sessions why something didn't work.
+- **UPDATE** when the decision is refined, expanded, or its status changes.
+- **ADD** reasoning if the original entry lacks a "why."
+- Only **DELETE** if the decision was recorded in error (wrong project, duplicate entry).
+
+### context.md — Aggressive curation
+- **Prune dead-end explorations.** If you explored 5 options and chose 1, delete the notes on the 4 rejected options. The decision file captures what was chosen and why.
+- **Consolidate findings.** If multiple explorations cover overlapping ground, merge them into one concise context file.
+- **DELETE** when a decision supersedes the exploration entirely (the exploration's value is now captured in the decision).
+
+### plan.md — Replace curation
+- **Keep the final version only.** Draft plans are noise once a final plan exists.
+- **UPDATE** during implementation — mark steps as complete, note adjustments.
+- **Do not create multiple plan versions.** Overwrite the plan when it changes.
+
+### lessons.md and patterns.md — Consolidation curation
+- **Merge similar lessons.** "Drizzle needs type casting" and "Drizzle enum handling requires explicit cast" are the same lesson — keep one entry with both examples.
+- **UPDATE** with new examples when the same pattern/lesson recurs.
+- **DELETE** if a lesson is proven wrong by later experience.
+- **Consolidate periodically.** If lessons.md exceeds ~30 entries, group related lessons under headers.
+
+## Metadata Format
+
+Every memory file includes metadata in the body (not YAML frontmatter):
+
+```
+**Status:** active | **Updated:** 2026-02-23
+```
+
+Status values:
+- `active` — Current and relevant
+- `complete` — Finished but still useful for reference
+- `archived` — Moved to archive/ (set by the completing skill on task completion)
+
+Place metadata on the line immediately after the title heading.
+
+## index.md Format
+
+The index is a structured pointer map with four sections:
+
+```
+# Memory Index
+
+**Updated:** 2026-02-23
+
+## Active Tasks
+- `task-memory/api-setup/` — Setting up REST API with Fastify (plan ready, implementing)
+
+## Project Knowledge
+- `project-memory/architecture.md` — Node.js + Fastify + PostgreSQL + Drizzle stack
+- `project-memory/requirements.md` — Core requirements and constraints
+
+## Recent Decisions
+- `project-memory/decisions/2026-02-23-tech-stack.md` — Chose Fastify + PostgreSQL + Drizzle
+- `project-memory/decisions/2026-02-23-auth-jwt.md` — JWT with refresh tokens for auth
+
+## Agent Lessons
+- `agent-memory/lessons.md` — 3 lessons recorded (Drizzle type casting, Fastify plugin order, test isolation)
+- `agent-memory/patterns.md` — 2 patterns recorded (route registration, error handling middleware)
+```
+
+Each entry is: `- \`file-path\` — one-line summary`
+
+### Updating the Index
+After every curated save:
+1. Re-read the current index.md
+2. Add entries for new files
+3. Update summaries for modified files
+4. Remove entries for deleted files
+5. Update the `**Updated:**` date
+
+### Rebuild Procedure (fallback)
+If `index.md` is missing, empty, or clearly stale (references files that don't exist):
+1. List all directories in `.mema/`: `project-memory/`, `task-memory/`, `agent-memory/`, `archive/`
+2. For each directory, list all `.md` files (excluding `_templates/`)
+3. Read the first 3 lines of each file to get title and metadata
+4. Generate index entries in the format above
+5. Write the rebuilt `index.md`
+
+This procedure makes the index a **rebuildable cache** — it's convenient but never the only copy of truth. The actual files in `.mema/` are the source of truth.

package/skills/create-skill/SKILL.md

@@ -0,0 +1,242 @@
+---
+description: Generate a new memory-aware Claude Code skill. Creates a SKILL.md file with the correct memory lifecycle phases based on the skill's complexity.
+---
+
+# /create-skill — Generate Memory-Aware Skills
+
+You are creating a new Claude Code skill that integrates with mema-kit's memory protocol. Follow these steps carefully.
+
+## Step 1: Interview
+
+Gather the following from the user. Keep it to **2-3 exchanges max** — don't over-interview.
+
+### Required:
+1. **Skill name** — kebab-case (e.g., `review`, `debug`, `migrate`). If the user gives a name with spaces or camelCase, convert it.
+2. **Purpose** — What does this skill do? One sentence is enough.
+
+### Optional (offer sensible defaults):
+3. **Memory needs** — Does this skill need to:
+   - **Read** memory (load context, architecture, lessons) — most skills
+   - **Write** memory (save decisions, findings, lessons) — skills that produce knowledge
+   - **Both** (default) — most useful skills both read and write
+4. **Complexity level**:
+   - **Simple** — Read-only or minimal memory. 3 phases: AUTO-LOAD, WORK, REPORT. Good for: code review, linting, quick lookups.
+   - **Standard** (default) — Full 4-phase lifecycle. Good for: most skills that produce and consume knowledge.
+   - **Advanced** — Full lifecycle + task management, archiving, and lesson learning. Good for: implementation skills, multi-step workflows.
+
+If the user doesn't specify memory needs or complexity, default to **both** and **standard**.
+
+## Step 2: Generate SKILL.md
+
+Based on the interview answers, generate a SKILL.md file. Use the appropriate template below based on complexity level.
+
+**Critical rule:** Generated skills reference `_memory-protocol.md` for curation rules. NEVER duplicate the memory protocol content inside generated skills.
+
+---
+
+### Simple Template (3 phases)
+
+```markdown
+---
+description: [User's purpose description]
+---
+
+# /[skill-name] — [Title]
+
+You are executing the /[skill-name] skill. Follow these steps carefully.
+
+## Phase 1: AUTO-LOAD
+
+1. Read `.mema/index.md` to understand current project state
+2. If `index.md` is missing or empty, inform the user to run `/onboard` first
+3. Based on the user's request, identify and read relevant memory files
+4. Read only what's needed — don't load everything
+
+## Phase 2: WORK
+
+[Core skill logic goes here — describe what the skill does step by step]
+
+1. [First action]
+2. [Second action]
+3. [Third action]
+
+Use the loaded memory context to inform your work. Reference architecture decisions, past lessons, and patterns where relevant.
+
+## Phase 3: REPORT
+
+Summarize what was done and any findings. If you discovered anything worth preserving, tell the user:
+
+"I noticed [finding]. Consider saving this as a lesson/decision/pattern using a memory-writing skill."
+
+Do NOT modify memory files directly in a simple skill.
+```
+
+---
+
+### Standard Template (4 phases)
+
+```markdown
+---
+description: [User's purpose description]
+---
+
+# /[skill-name] — [Title]
+
+You are executing the /[skill-name] skill. Follow these steps carefully.
+
+## Phase 1: AUTO-LOAD
+
+1. Read `.mema/index.md` to understand current project state
+2. If `index.md` is missing or empty, run the **Rebuild Procedure** from `_memory-protocol.md`
+3. Based on the user's request, identify and read relevant memory files
+4. Read only what's needed — don't load everything
+
+**Relevant memory for this skill:**
+- `project-memory/architecture.md` — for technical context
+- `project-memory/decisions/` — for past decisions related to this work
+- `agent-memory/lessons.md` — for mistakes to avoid
+- `agent-memory/patterns.md` — for reusable approaches
+- [Add or remove entries based on the skill's purpose]
+
+## Phase 2: WORK
+
+[Core skill logic goes here — describe what the skill does step by step]
+
+1. [First action]
+2. [Second action]
+3. [Third action]
+
+Use the loaded memory context to inform your work.
+
+## Phase 3: AUTO-SAVE & CURATE
+
+Follow the curation rules in `_memory-protocol.md`. For each piece of knowledge produced:
+
+- **Decisions made** → ADD to `project-memory/decisions/YYYY-MM-DD-short-name.md`
+- **Architecture changes** → UPDATE `project-memory/architecture.md`
+- **Lessons learned** → ADD/UPDATE `agent-memory/lessons.md`
+- **Patterns discovered** → ADD/UPDATE `agent-memory/patterns.md`
+- **Exploration findings** → ADD to appropriate `task-memory/` or `project-memory/` file
+
+Apply ADD/UPDATE/DELETE/NOOP to each memory file. Most files will be NOOP.
+
+## Phase 4: AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Re-read the current index
+2. Add entries for new files
+3. Update summaries for modified files
+4. Remove entries for deleted files
+5. Update the `**Updated:**` date
+```
+
+---
+
+### Advanced Template (4 phases + task management)
+
+```markdown
+---
+description: [User's purpose description]
+---
+
+# /[skill-name] — [Title]
+
+You are executing the /[skill-name] skill. Follow these steps carefully.
+
+## Phase 1: AUTO-LOAD
+
+1. Read `.mema/index.md` to understand current project state
+2. If `index.md` is missing or empty, run the **Rebuild Procedure** from `_memory-protocol.md`
+3. Based on the user's request, identify and read relevant memory files:
+   - Task-specific: `task-memory/[task-name]/` (context, plan, status)
+   - Project-wide: `project-memory/architecture.md`, relevant decisions
+   - Agent knowledge: `agent-memory/lessons.md`, `agent-memory/patterns.md`
+4. Read only what's needed — don't load everything
+
+## Phase 2: WORK
+
+### 2a: Task Setup
+If no task directory exists for this work:
+1. Create `task-memory/[task-name]/`
+2. Write initial `context.md` with the task description and relevant findings
+
+If a task directory exists, read the current status and continue where you left off.
+
+### 2b: Core Work
+
+[Core skill logic goes here — describe what the skill does step by step]
+
+1. [First action]
+2. [Second action]
+3. [Third action]
+
+Track progress by updating `task-memory/[task-name]/status.md` as you go.
+
+### 2c: Learn
+
+After completing work, reflect:
+- Did anything unexpected happen? → Record as a lesson
+- Did you use a pattern that worked well? → Record as a pattern
+- Did any previous lesson prove wrong? → Update or delete it
+
+## Phase 3: AUTO-SAVE & CURATE
+
+Follow the curation rules in `_memory-protocol.md`. For each piece of knowledge produced:
+
+- **Decisions made** → ADD to `project-memory/decisions/YYYY-MM-DD-short-name.md`
+- **Architecture changes** → UPDATE `project-memory/architecture.md`
+- **Lessons learned** → ADD/UPDATE `agent-memory/lessons.md`
+- **Patterns discovered** → ADD/UPDATE `agent-memory/patterns.md`
+- **Task progress** → UPDATE `task-memory/[task-name]/status.md`
+
+Apply ADD/UPDATE/DELETE/NOOP to each memory file. Most files will be NOOP.
+
+### Task Completion
+If the task is fully complete:
+1. Mark `task-memory/[task-name]/status.md` as `**Status:** complete`
+2. Move `task-memory/[task-name]/` to `archive/[task-name]/`
+3. Remove the task from "Active Tasks" in `index.md`
+
+## Phase 4: AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Re-read the current index
+2. Add entries for new files
+3. Update summaries for modified files
+4. Remove entries for deleted files
+5. Update the `**Updated:**` date
+```
+
+---
+
+## Step 3: Write the File
+
+1. Write the generated SKILL.md to `.claude/skills/[skill-name]/SKILL.md`
+2. Create the directory if it doesn't exist
+3. If the file already exists, warn the user and ask before overwriting
+
+## Step 4: Verify
+
+Read back the file you just wrote and confirm:
+- The `description` frontmatter is present and accurate
+- The skill name is correct throughout
+- Memory file paths use `.mema/` (not `.praxis/` or any other prefix)
+- The skill references `_memory-protocol.md` for curation rules (standard and advanced only)
+- No memory protocol content is duplicated inside the skill
+
+## Step 5: Confirm
+
+Tell the user:
+
+```
+Skill created: /[skill-name]
+
+Location: .claude/skills/[skill-name]/SKILL.md
+Type: [simple|standard|advanced]
+Memory: [read-only|write-only|read+write]
+
+To use it:
+  /[skill-name] [your request]
+
+The skill follows the mema-kit memory protocol and will [read from / write to / read from and write to] .mema/ automatically.
+```

package/skills/onboard/SKILL.md

@@ -0,0 +1,417 @@
+---
+description: Bootstrap the mema-kit memory system for this project. Creates .mema/ directory, scans the project, populates initial memory, and configures CLAUDE.md and .gitignore.
+---
+
+# /onboard — Project Memory Bootstrap
+
+You are setting up the mema-kit memory system for this project. Follow these steps carefully. This command is idempotent — safe to re-run. Never overwrite existing data.
+
+## Step 1: Check Current State
+
+Before creating anything, assess what already exists:
+
+1. Check if `.mema/` directory exists
+2. Check if `CLAUDE.md` exists and whether it contains a `## Memory System` section
+3. Check if `.gitignore` exists and whether it contains `.mema` entries
+
+Report what you found to the user: "Setting up mema-kit. Found existing .mema/ directory — will verify and repair." or "Fresh setup — creating everything from scratch."
+
+## Step 2: Create .mema/ Directory Structure
+
+Create the following directories if they don't already exist:
+
+```
+.mema/
+├── _templates/
+├── project-memory/
+│   └── decisions/
+├── task-memory/
+├── agent-memory/
+└── archive/
+```
+
+For each directory: if it exists, skip it. If it doesn't, create it.
+
+## Step 3: Write Template Files
+
+Write the following files to `.mema/_templates/`. If a template file already exists, **skip it** (the user may have customized it).
+
+### `.mema/_templates/decision.md`
+
+```
+# [Decision Title]
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Context
+<!-- What situation or question prompted this decision? What problem are we solving? -->
+
+## Decision
+<!-- What was decided? Be specific and concrete. -->
+
+## Options Considered
+
+### Option A: [Name]
+<!-- Brief description. Why chosen/rejected. -->
+
+### Option B: [Name]
+<!-- Brief description. Why chosen/rejected. -->
+
+## Reasoning
+<!-- Why this option was selected. What factors mattered most? What trade-offs were accepted? -->
+
+## Consequences
+<!-- What are the implications? What does this enable or constrain? Any known trade-offs or risks? -->
+```
+
+### `.mema/_templates/context.md`
+
+```
+# [Topic] — Exploration Context
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Summary
+<!-- 2-3 sentence overview of what was explored and the key takeaway. -->
+
+## Key Findings
+<!-- Bullet list of important facts, constraints, or insights discovered. Be specific and concise. -->
+
+-
+-
+-
+
+## Open Questions
+<!-- What remains unresolved? What needs further exploration or a decision? -->
+
+-
+-
+
+## Relates To
+<!-- Links to related memory files (decisions, other context, plans). Use relative paths. -->
+
+-
+```
+
+### `.mema/_templates/plan.md`
+
+```
+# [Task Name] — Implementation Plan
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## General Plan
+<!-- High-level approach: architecture decisions, component design, data flow. Keep it to 1-2 paragraphs or a short list. This should answer "what are we building and how does it fit together?" -->
+
+## Detailed Plan
+<!-- Step-by-step implementation tasks. Each step should be specific enough to implement directly. -->
+
+### Step 1: [Action]
+<!-- What to do, which files to create/modify, any dependencies on prior steps. -->
+- Files: `path/to/file`
+- Details:
+
+### Step 2: [Action]
+- Files: `path/to/file`
+- Details:
+
+### Step 3: [Action]
+- Files: `path/to/file`
+- Details:
+
+## Out of Scope
+<!-- What this plan explicitly does NOT cover. Prevents scope creep during implementation. -->
+
+-
+```
+
+### `.mema/_templates/lessons.md`
+
+```
+# Agent Lessons
+
+**Updated:** YYYY-MM-DD
+
+## Lessons
+
+### [Short Title]
+<!-- One-sentence lesson. -->
+- **Context:** <!-- When/how this was discovered. -->
+- **Example:** <!-- Concrete code example or scenario if applicable. -->
+
+---
+
+<!-- Add new lessons above this line. When entries exceed ~30, consolidate related lessons under grouped headers. -->
+```
+
+### `.mema/_templates/patterns.md`
+
+```
+# Agent Patterns
+
+**Updated:** YYYY-MM-DD
+
+## Patterns
+
+### [Pattern Name]
+- **Structure:** <!-- How the pattern is organized. -->
+- **Example:** <!-- Concrete usage example. -->
+
+---
+
+<!-- Add new patterns above this line. -->
+```
+
+### `.mema/_templates/status.md`
+
+```
+# [Task Name] — Status
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Progress
+
+- [ ] Step 1: [description]
+- [ ] Step 2: [description]
+- [ ] Step 3: [description]
+
+## Notes
+<!-- Any blockers, deviations from plan, or important observations during implementation. -->
+
+## Completed
+**Completed:**
+```
+
+## Step 4: Scan the Project
+
+This is the intelligence step. Read and analyze the project to populate memory with real content instead of empty placeholders.
+
+### 4a: Detect Project Type and Stack
+
+Read the following files (skip any that don't exist):
+
+1. `package.json` or `pyproject.toml` or `Cargo.toml` or `go.mod` or `pom.xml` or `Gemfile` — to identify language, framework, and dependencies
+2. `README.md` — to understand project purpose and setup
+3. `CLAUDE.md` — to understand existing conventions and instructions
+4. `tsconfig.json` or equivalent config files — to understand build setup
+
+### 4b: Scan Directory Structure
+
+List the top-level directories and key subdirectories (1-2 levels deep) to understand the project layout. Note:
+- Source code location (`src/`, `lib/`, `app/`, etc.)
+- Test location (`tests/`, `__tests__/`, `test/`, etc.)
+- Config files present
+- Any existing documentation
+
+### 4c: Read Representative Source Files
+
+Pick 2-3 source files that best represent the codebase patterns:
+- The main entry point (e.g., `src/index.ts`, `main.py`, `main.go`)
+- A representative module/component
+- A test file (if tests exist)
+
+Read these to understand coding patterns, style, and architecture.
+
+### 4d: Summarize Findings
+
+Before writing memory, compile your findings:
+- **Project name** and purpose
+- **Language/framework/stack** with versions
+- **Architecture pattern** (monolith, microservices, CLI tool, library, etc.)
+- **Key directories** and what they contain
+- **Testing setup** (framework, patterns)
+- **Build/run commands**
+- **Notable conventions** (naming, patterns, config)
+
+## Step 5: Populate Initial Memory
+
+Using the scan findings, create memory files with **real content** (not empty placeholders).
+
+### `.mema/project-memory/architecture.md`
+
+Write an architecture overview based on what you discovered. Include:
+- Tech stack with versions
+- Project structure (key directories and their purposes)
+- Architecture pattern
+- Key entry points
+- Build and run commands
+
+Example format:
+
+```
+# Project Architecture
+
+**Status:** active | **Updated:** [today's date]
+
+## Stack
+- **Language:** TypeScript 5.x
+- **Runtime:** Node.js 20+
+- **Framework:** Fastify 4.x
+- **Database:** PostgreSQL 16 via Drizzle ORM
+- **Testing:** Vitest
+
+## Structure
+- `src/` — Application source code
+  - `routes/` — API route handlers
+  - `services/` — Business logic
+  - `db/` — Database schema and migrations
+- `tests/` — Test files mirroring src/ structure
+
+## Architecture
+REST API following controller → service → repository layers.
+Entry point: `src/app.ts`
+
+## Commands
+- `npm run dev` — Start development server
+- `npm test` — Run test suite
+- `npm run build` — Build for production
+```
+
+### `.mema/project-memory/requirements.md`
+
+Write a requirements summary based on README, package.json description, and observed functionality:
+
+```
+# Project Requirements
+
+**Status:** active | **Updated:** [today's date]
+
+## Purpose
+[What this project does, based on README and code]
+
+## Key Requirements
+- [Requirement discovered from code/docs]
+- [Requirement discovered from code/docs]
+
+## Constraints
+- [Any constraints discovered (Node version, dependencies, etc.)]
+```
+
+### `.mema/agent-memory/lessons.md`
+
+Create a starter lessons file with any project-specific gotchas discovered during scanning:
+
+```
+# Agent Lessons
+
+**Updated:** [today's date]
+
+## Lessons
+
+<!-- Lessons will be added here as the agent learns from development experience. -->
+```
+
+If you discovered anything notable during scanning (e.g., unusual config, non-obvious setup steps), add it as the first lesson.
+
+### `.mema/agent-memory/patterns.md`
+
+Create a starter patterns file. If you identified clear patterns from the source files you read, add them:
+
+```
+# Agent Patterns
+
+**Updated:** [today's date]
+
+## Patterns
+
+<!-- Patterns will be added here as the agent discovers reusable approaches. -->
+```
+
+### `.mema/index.md`
+
+Build the index from the files you just created:
+
+```
+# Memory Index
+
+**Updated:** [today's date]
+
+## Active Tasks
+
+## Project Knowledge
+- `project-memory/architecture.md` — [one-line summary of stack/architecture]
+- `project-memory/requirements.md` — [one-line summary of purpose]
+
+## Recent Decisions
+
+## Agent Lessons
+- `agent-memory/lessons.md` — [N] lessons recorded
+- `agent-memory/patterns.md` — [N] patterns recorded
+```
+
+## Step 6: Update CLAUDE.md
+
+1. Read the current `CLAUDE.md` (if it exists)
+2. Search for `## Memory System` in the file content
+3. If found → **skip this step** (already configured)
+4. If not found → append the following section at the end of the file
+5. If `CLAUDE.md` doesn't exist → create the file with this content
+
+Append this section:
+
+```
+## Memory System
+
+This project uses mema-kit for persistent memory across sessions.
+
+Memory lives in `.mema/`. At the start of each task, read `.mema/index.md` to load relevant context. After completing work, curate and save knowledge following the memory protocol in `.claude/skills/_memory-protocol.md`.
+
+Memory is managed automatically by skills — do not manually modify `.mema/` files unless correcting an error.
+```
+
+## Step 7: Update .gitignore
+
+1. Read the current `.gitignore` (if it exists)
+2. Search for `.mema` in the file content
+3. If found → **skip this step** (already configured)
+4. If not found → append the following block at the end of the file
+5. If `.gitignore` doesn't exist → create the file with this content
+
+Append this block:
+
+```
+# mema-kit memory (developer-local)
+.mema/*
+# Uncomment to share project decisions with your team:
+# !.mema/project-memory/
+```
+
+## Step 8: Confirm to the User
+
+Print a summary of what was done, including what you discovered about the project:
+
+```
+mema-kit initialized! Here's what was set up:
+
+[check] .mema/ directory structure (memory system)
+[check] Memory templates in .mema/_templates/
+[check] CLAUDE.md updated with memory system conventions
+[check] .gitignore updated to exclude .mema/
+
+Project scan results:
+- [Language/framework discovered]
+- [Architecture pattern discovered]
+- [N] source directories mapped
+- [Notable findings]
+
+Memory populated:
+- architecture.md — [summary]
+- requirements.md — [summary]
+- lessons.md — [N] initial lessons
+- patterns.md — [N] initial patterns
+
+Next: Start working on your project. Memory will be loaded and saved automatically by any mema-kit skill.
+```
+
+If this was a re-run (some items already existed), adjust the summary to show what was verified vs. created:
+
+```
+mema-kit verified! Everything looks good:
+
+[check] .mema/ directory structure — already exists, verified
+[check] Memory templates — already exist, skipped
+[check] CLAUDE.md — memory section already present
+[check] .gitignore — .mema/ already excluded
+
+Your setup is intact. No changes were needed.
+```

package/templates/context.md

@@ -0,0 +1,24 @@
+# [Topic] — Exploration Context
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Summary
+<!-- 2-3 sentence overview of what was explored and the key takeaway. -->
+
+## Key Findings
+<!-- Bullet list of important facts, constraints, or insights discovered. Be specific and concise. -->
+
+-
+-
+-
+
+## Open Questions
+<!-- What remains unresolved? What needs further exploration or a decision? -->
+
+-
+-
+
+## Relates To
+<!-- Links to related memory files (decisions, other context, plans). Use relative paths. -->
+
+-

package/templates/decision.md

@@ -0,0 +1,24 @@
+# [Decision Title]
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Context
+<!-- What situation or question prompted this decision? What problem are we solving? -->
+
+## Decision
+<!-- What was decided? Be specific and concrete. -->
+
+## Options Considered
+<!-- What alternatives were evaluated? For each: name, brief description, and why it was chosen or rejected. -->
+
+### Option A: [Name]
+<!-- Brief description. Why chosen/rejected. -->
+
+### Option B: [Name]
+<!-- Brief description. Why chosen/rejected. -->
+
+## Reasoning
+<!-- Why this option was selected. What factors mattered most? What trade-offs were accepted? -->
+
+## Consequences
+<!-- What are the implications? What does this enable or constrain? Any known trade-offs or risks? -->

package/templates/index.md

@@ -0,0 +1,15 @@
+# Memory Index
+
+**Updated:** YYYY-MM-DD
+
+<!-- Format: - `file-path` — one-line summary -->
+
+## Active Tasks
+
+## Project Knowledge
+- `project-memory/architecture.md` — Project architecture (not yet documented)
+- `project-memory/requirements.md` — Project requirements (not yet documented)
+
+## Recent Decisions
+
+## Agent Lessons

package/templates/lessons.md

@@ -0,0 +1,16 @@
+# Agent Lessons
+
+**Updated:** YYYY-MM-DD
+
+<!-- Lessons learned during development. Each entry is a mistake, surprise, or hard-won insight that future sessions should know about. -->
+
+## Lessons
+
+### [Short Title]
+<!-- One-sentence lesson. -->
+- **Context:** <!-- When/how this was discovered. -->
+- **Example:** <!-- Concrete code example or scenario if applicable. -->
+
+---
+
+<!-- Add new lessons above this line. When entries exceed ~30, consolidate related lessons under grouped headers. -->

package/templates/patterns.md

@@ -0,0 +1,16 @@
+# Agent Patterns
+
+**Updated:** YYYY-MM-DD
+
+<!-- Reusable patterns and approaches that worked well. Load these to apply proven solutions. -->
+
+## Patterns
+
+### [Pattern Name]
+<!-- What this pattern solves and when to use it. -->
+- **Structure:** <!-- How the pattern is organized (e.g., file layout, function signatures). -->
+- **Example:** <!-- Concrete usage example. -->
+
+---
+
+<!-- Add new patterns above this line. -->

package/templates/plan.md

@@ -0,0 +1,27 @@
+# [Task Name] — Implementation Plan
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## General Plan
+<!-- High-level approach: architecture decisions, component design, data flow. Keep it to 1-2 paragraphs or a short list. This should answer "what are we building and how does it fit together?" -->
+
+## Detailed Plan
+<!-- Step-by-step implementation tasks. Each step should be specific enough to implement directly. -->
+
+### Step 1: [Action]
+<!-- What to do, which files to create/modify, any dependencies on prior steps. -->
+- Files: `path/to/file.ts`
+- Details:
+
+### Step 2: [Action]
+- Files: `path/to/file.ts`
+- Details:
+
+### Step 3: [Action]
+- Files: `path/to/file.ts`
+- Details:
+
+## Out of Scope
+<!-- What this plan explicitly does NOT cover. Prevents scope creep during implementation. -->
+
+-

package/templates/status.md

@@ -0,0 +1,17 @@
+# [Task Name] — Status
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Progress
+<!-- Check off steps as they complete. These should mirror the plan's detailed steps. -->
+
+- [ ] Step 1: [description]
+- [ ] Step 2: [description]
+- [ ] Step 3: [description]
+
+## Notes
+<!-- Any blockers, deviations from plan, or important observations during implementation. -->
+
+## Completed
+<!-- Date when all steps finished. Leave empty until done. -->
+**Completed:**