feat(context-keeper): Add session context persistence power

README.md

@@ -63,6 +63,13 @@ Documentation is available at https://kiro.dev/docs/powers/
 
 ---
 
+### context-keeper
+**Session Context Persistence** - Preserves session context across chat windows — automatically captures summaries when sessions end, restores them when new sessions begin, and maintains a persistent project memory file for long-term knowledge.
+
+**MCP Servers:** None (Knowledge Base Power)
+
+---
+
 ### cloudwatch-application-signals
 **Amazon CloudWatch Application Signals** - Monitor service health, analyze SLO compliance, and perform root cause analysis with distributed tracing and audit capabilities.
 

context-keeper/POWER.md

@@ -0,0 +1,65 @@
+---
+name: "context-keeper"
+displayName: "Context Keeper"
+description: "Preserves session context across chat windows — automatically captures summaries when sessions end, restores them when new sessions begin, and maintains a persistent project memory file for long-term knowledge."
+keywords: ["context", "session", "summary", "memory", "history", "continuity", "branch", "project-memory"]
+author: "Logesh"
+---
+
+# Context Keeper
+
+## Onboarding
+
+This power preserves your session context across Kiro chat windows. It works automatically — no configuration needed.
+
+### What gets installed
+
+- **4 hooks** that automate context capture and restore
+- **5 steering files** that guide the agent through each workflow
+
+### How it works
+
+1. **Auto-capture** (`agentStop`): When a session ends, the agent summarizes key decisions, files modified, patterns, preferences, and next steps into a structured markdown file in `.kiro/context-keeper/sessions/`.
+2. **Auto-restore** (`promptSubmit`): When a new session starts, the agent loads the most recent summary (preferring the current git branch) plus the project memory and any compressed history.
+3. **Manual snapshot** (`userTriggered`): Trigger anytime to save a point-in-time snapshot of the current session context.
+4. **Compress** (`userTriggered`): Consolidate older session summaries into a single compressed file to keep the store lean.
+
+### Session store location
+
+- Session summaries: `.kiro/context-keeper/sessions/`
+- Project memory: `.kiro/context-keeper/project-memory.md`
+
+## Steering
+
+### Capture context
+- workflow: capture-context
+- description: Guides the agent to generate a structured session summary with 7 sections, write it to the session store, update project memory, and clean up old files.
+- file: steering/capture-context.md
+
+### Restore context
+- workflow: restore-context
+- description: Guides the agent to find the most recent branch-scoped summary, load project memory and compressed history, and present all as labeled context.
+- file: steering/restore-context.md
+
+### Snapshot context
+- workflow: snapshot-context
+- description: Guides the agent to create a manual point-in-time snapshot using the same structured format.
+- file: steering/snapshot-context.md
+
+### Update project memory
+- workflow: project-memory-update
+- description: Guides the agent to append new learnings to the persistent project memory file without duplicating existing content.
+- file: steering/project-memory-update.md
+
+### Compress context
+- workflow: compress-context
+- description: Guides the agent to merge older session summaries into a single compressed file, deduplicating content and discarding resolved questions.
+- file: steering/compress-context.md
+
+## License and support
+
+This power is open source (MIT). No data is collected or transmitted — all context is stored locally in your workspace.
+
+- [License](https://github.com/logesh4v/context-keeper/blob/main/LICENSE)
+- [Privacy Policy](https://github.com/logesh4v/context-keeper/blob/main/README.md#license) — No data collection; all files stay in your local `.kiro/` directory
+- [Support / Issues](https://github.com/logesh4v/context-keeper/issues)

context-keeper/hooks/capture-context.kiro.hook

@@ -0,0 +1,12 @@
+{
+  "name": "Capture Session Context",
+  "version": "1.0.0",
+  "description": "Automatically captures a structured summary of the session when it ends, updates project memory, and cleans up old files.",
+  "when": {
+    "type": "agentStop"
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "A session just ended. Follow the steering/capture-context.md guide to capture the session context:\n\n1. Detect the current git branch: run `git rev-parse --abbrev-ref HEAD`. If it fails, use 'unknown'.\n2. Sanitize the branch name for filenames (replace / \\ : * ? \" < > | with hyphens, collapse consecutive hyphens, trim leading/trailing hyphens).\n3. Generate a structured session summary with these 7 sections in order: Session Metadata, Key Decisions, Files Modified, Architectural Patterns, User Preferences, Unresolved Questions, Next Steps. Use 'None captured' for empty sections. Keep it under 150 lines.\n4. Create the directory `.kiro/context-keeper/sessions/` if it doesn't exist.\n5. Write the summary to `.kiro/context-keeper/sessions/{YYYY}-{MM}-{DD}T{HH}-{mm}-{ss}-{sanitized-branch}.md`.\n6. Update project memory: follow steering/project-memory-update.md to append new learnings to `.kiro/context-keeper/project-memory.md` (create with empty headings if missing).\n7. Cleanup: if more than 20 files in the sessions directory, delete the oldest (lexicographically smallest) to bring count to 20."
+  }
+}

context-keeper/hooks/compress-context.kiro.hook

@@ -0,0 +1,12 @@
+{
+  "name": "Compress Context",
+  "version": "1.0.0",
+  "description": "Consolidate older session summaries into a single compressed file to keep the session store lean.",
+  "when": {
+    "type": "userTriggered"
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "The user wants to compress older session summaries. Follow the steering/compress-context.md guide:\n\n1. List all files in `.kiro/context-keeper/sessions/`.\n2. Count session summary files (exclude compressed-*.md from the count).\n3. If fewer than 4 session files exist, inform the user: 'Not enough session summaries to compress (need at least 4, found {count}).' and stop.\n4. Sort session files lexicographically. The 3 most recent are preserved unchanged.\n5. Read all older session files and any existing compressed-*.md files.\n6. Extract Key Decisions, Architectural Patterns, and User Preferences from each. Discard Session Metadata, Files Modified, Unresolved Questions, and Next Steps.\n7. Deduplicate extracted content (case-insensitive).\n8. Write the compressed summary to `.kiro/context-keeper/sessions/compressed-{YYYY}-{MM}-{DD}T{HH}-{mm}-{ss}.md`. Keep it under 150 lines.\n9. Delete the original merged files.\n10. Confirm to the user how many summaries were compressed and which file was created."
+  }
+}

context-keeper/hooks/restore-context.kiro.hook

@@ -0,0 +1,12 @@
+{
+  "name": "Restore Session Context",
+  "version": "1.0.0",
+  "description": "Automatically loads prior session context when a new session starts, preferring the current branch.",
+  "when": {
+    "type": "promptSubmit"
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "A new session is starting. Follow the steering/restore-context.md guide to load prior context:\n\n1. Detect the current git branch: run `git rev-parse --abbrev-ref HEAD`. If it fails, use 'unknown'.\n2. Sanitize the branch name (replace / \\ : * ? \" < > | with hyphens).\n3. List files in `.kiro/context-keeper/sessions/`. If the directory doesn't exist or is empty, proceed silently without any error.\n4. Find the most recent session summary matching the current branch (exclude compressed- files). If no match, fall back to the most recent from any branch.\n5. If a summary was found from a different branch, note the source branch.\n6. Read `.kiro/context-keeper/project-memory.md` if it exists.\n7. Read the most recent `compressed-*.md` file if one exists.\n8. Present all loaded context in clearly labeled sections. If a summary is from a different branch, indicate it. Skip sections that have no content."
+  }
+}

context-keeper/hooks/snapshot-context.kiro.hook

@@ -0,0 +1,12 @@
+{
+  "name": "Snapshot Context",
+  "version": "1.0.0",
+  "description": "Manually trigger a context snapshot to preserve the current session state on demand.",
+  "when": {
+    "type": "userTriggered"
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "The user wants to save a manual context snapshot. Follow the steering/snapshot-context.md guide:\n\n1. Detect the current git branch: run `git rev-parse --abbrev-ref HEAD`. If it fails, use 'unknown'.\n2. Sanitize the branch name (replace / \\ : * ? \" < > | with hyphens).\n3. Generate a structured session summary with the same 7-section format as automatic capture. Use 'None captured' for empty sections. Keep it under 150 lines.\n4. Create the directory `.kiro/context-keeper/sessions/` if it doesn't exist.\n5. Write the summary to `.kiro/context-keeper/sessions/{YYYY}-{MM}-{DD}T{HH}-{mm}-{ss}-{sanitized-branch}-manual.md`.\n6. Confirm the save to the user by displaying the file path."
+  }
+}

context-keeper/steering/capture-context.md

@@ -0,0 +1,56 @@
+---
+inclusion: manual
+---
+
+# Capture Context — Session Summary Guide
+
+When a session ends, generate a structured summary of the session and save it to the session store.
+
+## Steps
+
+1. Detect the current git branch using `git rev-parse --abbrev-ref HEAD`. If detection fails, use `unknown`.
+2. Sanitize the branch name for use in filenames: replace `/`, `\`, `:`, `*`, `?`, `"`, `<`, `>`, `|` with hyphens. Collapse consecutive hyphens. Trim leading/trailing hyphens.
+3. Generate the summary following the format below.
+4. Write the summary to `.kiro/context-keeper/sessions/{timestamp}-{sanitized-branch}.md`
+   - Timestamp format: `YYYY-MM-DDTHH-mm-ss` (hyphens instead of colons)
+   - Create the `.kiro/context-keeper/sessions/` directory if it doesn't exist.
+5. After writing, follow the `steering/project-memory-update.md` guide to update the project memory file.
+6. Run cleanup: if more than 20 files exist in the sessions directory, delete the oldest files (sorted lexicographically) to bring the count back to 20.
+
+## Summary Format
+
+The summary must contain exactly these 7 sections in this order:
+
+```markdown
+# Session Summary
+
+## Session Metadata
+- **Session Start**: {ISO 8601 timestamp}
+- **Session End**: {ISO 8601 timestamp}
+- **Workspace**: {absolute path to workspace root}
+- **Branch**: {original branch name, not sanitized}
+
+## Key Decisions
+- {Decision with one-sentence rationale}
+
+## Files Modified
+- `{relative/path/to/file}` — {one-line description of change}
+
+## Architectural Patterns
+- {Pattern observed or discussed}
+
+## User Preferences
+- {Preference expressed by the user}
+
+## Unresolved Questions
+- {Question that was raised but not resolved}
+
+## Next Steps
+- {Action item for the next session}
+```
+
+## Rules
+
+- If no content exists for a section, include the heading with the text `None captured`. Never omit a section.
+- Keep the summary to **150 lines or fewer**. If content exceeds this, truncate proportionally across sections.
+- Both automatic and manual summaries count toward the 20-file limit.

context-keeper/steering/compress-context.md

@@ -0,0 +1,50 @@
+---
+inclusion: manual
+---
+
+# Compress Context — Session Summary Compression Guide
+
+When the user triggers compression, consolidate older session summaries into a single compressed file.
+
+## Steps
+
+1. List all files in `.kiro/context-keeper/sessions/`.
+2. Count session summary files (exclude `compressed-*.md` files from the count).
+3. If fewer than **4 session files** exist, inform the user: "Not enough session summaries to compress (need at least 4, found {count})." and stop.
+4. Sort session files lexicographically (chronological order due to ISO 8601 prefix).
+5. Identify the **3 most recent** session files — these are preserved unchanged.
+6. All remaining session files (and any existing `compressed-*.md` files) are candidates for merging.
+7. Read each candidate file and extract:
+   - **Key Decisions** — bullet points from the Key Decisions section
+   - **Architectural Patterns** — bullet points from the Architectural Patterns section
+   - **User Preferences** — bullet points from the User Preferences section
+8. **Discard** from candidates: Session Metadata, Files Modified, Unresolved Questions, and Next Steps (these are session-specific).
+9. **Deduplicate** extracted content across all candidate files (case-insensitive comparison, ignoring bullet markers).
+10. Write the compressed summary to `.kiro/context-keeper/sessions/compressed-{timestamp}.md`
+    - Timestamp format: `YYYY-MM-DDTHH-mm-ss`
+11. Delete all candidate files (the ones that were merged).
+12. Confirm to the user: "Compressed {count} session summaries into {filename}. {kept} most recent summaries preserved."
+
+## Compressed Summary Format
+
+```markdown
+# Compressed Summary
+- **Compressed At**: {ISO 8601 timestamp}
+- **Source Sessions**: {count} sessions from {earliest date} to {latest date}
+
+## Key Decisions
+- {Deduplicated decision}
+
+## Architectural Patterns
+- {Deduplicated pattern}
+
+## User Preferences
+- {Deduplicated preference}
+```
+
+## Rules
+
+- The compressed summary must be **150 lines or fewer**. If content exceeds this, truncate proportionally across sections.
+- Always preserve the 3 most recent session files untouched.
+- Delete originals only after the compressed file is successfully written.
+- The minimum threshold is 4 session files. Below that, compression is skipped.

context-keeper/steering/project-memory-update.md

@@ -0,0 +1,52 @@
+---
+inclusion: manual
+---
+
+# Project Memory Update Guide
+
+After each session capture, update the persistent project memory file with new learnings.
+
+## File Location
+
+`.kiro/context-keeper/project-memory.md`
+
+## Steps
+
+1. Read the existing project memory file. If it doesn't exist, create it with the 5 section headings below (empty sections).
+2. Review the session that just ended. Identify any new learnings about:
+   - **Project Architecture** — directory structure, service boundaries, deployment topology
+   - **Tech Stack** — languages, frameworks, databases, tools, versions
+   - **Coding Conventions** — style preferences, naming conventions, import patterns
+   - **Key Patterns** — design patterns, architectural patterns, data access patterns
+   - **Team Preferences** — workflow preferences, review processes, commit conventions
+3. For each new learning, check if it already exists in the project memory (case-insensitive comparison, ignoring bullet markers).
+4. Append only genuinely new information under the appropriate section heading.
+5. If the file exceeds **200 lines** after the update, consolidate: trim proportionally across sections, keeping the most recent entries (entries at the end of each section are more recent).
+
+## Format
+
+```markdown
+# Project Memory
+
+## Project Architecture
+- {Learning about project structure}
+
+## Tech Stack
+- {Learning about technologies used}
+
+## Coding Conventions
+- {Learning about coding style}
+
+## Key Patterns
+- {Learning about design patterns}
+
+## Team Preferences
+- {Learning about team workflow}
+```
+
+## Rules
+
+- Never rewrite the entire file. Only append new learnings.
+- Never duplicate information that already exists.
+- Keep entries as concise bullet points.
+- The 200-line cap is enforced after every update.

context-keeper/steering/restore-context.md

@@ -0,0 +1,44 @@
+---
+inclusion: manual
+---
+
+# Restore Context — Session Context Loading Guide
+
+When a new session starts, load prior context from the session store and present it to the agent.
+
+## Steps
+
+1. Detect the current git branch using `git rev-parse --abbrev-ref HEAD`. If detection fails, use `unknown`.
+2. Sanitize the branch name (same rules as capture: replace unsafe chars with hyphens).
+3. List all files in `.kiro/context-keeper/sessions/`.
+4. **Select the most recent session summary:**
+   - Filter for files whose filename contains the sanitized branch name (exclude `compressed-` files).
+   - If matching files exist, select the most recent (lexicographically last).
+   - If no files match the current branch, fall back to the most recent file from any branch.
+5. **Load Project Memory:** If `.kiro/context-keeper/project-memory.md` exists, read it.
+6. **Load Compressed Summary:** If any `compressed-*.md` file exists in the sessions directory, read the most recent one.
+7. Present all loaded context in clearly labeled sections (see format below).
+
+## Presentation Format
+
+```
+--- Prior Session Context ---
+{Contents of the selected session summary}
+--- End Prior Session Context ---
+
+--- Project Memory ---
+{Contents of project-memory.md}
+--- End Project Memory ---
+
+--- Historical Context (Compressed) ---
+{Contents of the compressed summary}
+--- End Historical Context ---
+```
+
+## Rules
+
+- If the selected summary is from a **different branch** than the current branch, add a note: `(Source: {branch-name} branch)` after the "Prior Session Context" header.
+- If **no session summaries exist**, proceed silently. Do not display an error or empty sections.
+- If **Project Memory does not exist**, skip that section silently.
+- If **no Compressed Summary exists**, skip that section silently.
+- Only present sections that have content.

context-keeper/steering/snapshot-context.md

@@ -0,0 +1,23 @@
+---
+inclusion: manual
+---
+
+# Snapshot Context — Manual Context Capture Guide
+
+When the user triggers a manual snapshot, generate a session summary and save it with a `-manual` suffix.
+
+## Steps
+
+1. Detect the current git branch using `git rev-parse --abbrev-ref HEAD`. If detection fails, use `unknown`.
+2. Sanitize the branch name (same rules as capture: replace unsafe chars with hyphens).
+3. Generate a summary using the exact same 7-section format defined in `steering/capture-context.md`.
+4. Write the summary to `.kiro/context-keeper/sessions/{timestamp}-{sanitized-branch}-manual.md`
+   - Timestamp format: `YYYY-MM-DDTHH-mm-ss` (hyphens instead of colons)
+   - Create the `.kiro/context-keeper/sessions/` directory if it doesn't exist.
+5. Confirm the save to the user by displaying the file path.
+
+## Rules
+
+- Follow the same 150-line cap and "None captured" rules as automatic capture.
+- Manual snapshots count toward the 20-file limit in the session store.
+- The `-manual` suffix goes after the branch name: `{timestamp}-{branch}-manual.md`