From 25cb2b5ba6ff87a477d640082acecfe118bbc012 Mon Sep 17 00:00:00 2001 From: Logesh Date: Wed, 13 May 2026 12:16:40 +0530 Subject: [PATCH] feat(context-keeper): Add session context persistence power MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds Context Keeper — a Knowledge Base Power that preserves session context across Kiro chat windows using hooks and steering files. - Auto-captures structured session summaries on agentStop - Auto-restores prior context on promptSubmit (branch-aware) - Manual snapshot and compression via userTriggered hooks - Maintains persistent project memory across all sessions - Zero external dependencies, pure hooks + steering architecture --- README.md | 7 ++ context-keeper/POWER.md | 65 +++++++++++++++++++ .../hooks/capture-context.kiro.hook | 12 ++++ .../hooks/compress-context.kiro.hook | 12 ++++ .../hooks/restore-context.kiro.hook | 12 ++++ .../hooks/snapshot-context.kiro.hook | 12 ++++ context-keeper/steering/capture-context.md | 56 ++++++++++++++++ context-keeper/steering/compress-context.md | 50 ++++++++++++++ .../steering/project-memory-update.md | 52 +++++++++++++++ context-keeper/steering/restore-context.md | 44 +++++++++++++ context-keeper/steering/snapshot-context.md | 23 +++++++ 11 files changed, 345 insertions(+) create mode 100644 context-keeper/POWER.md create mode 100644 context-keeper/hooks/capture-context.kiro.hook create mode 100644 context-keeper/hooks/compress-context.kiro.hook create mode 100644 context-keeper/hooks/restore-context.kiro.hook create mode 100644 context-keeper/hooks/snapshot-context.kiro.hook create mode 100644 context-keeper/steering/capture-context.md create mode 100644 context-keeper/steering/compress-context.md create mode 100644 context-keeper/steering/project-memory-update.md create mode 100644 context-keeper/steering/restore-context.md create mode 100644 context-keeper/steering/snapshot-context.md diff --git a/README.md b/README.md index 5fc0fee..a4d6ba4 100644 --- a/README.md +++ b/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. diff --git a/context-keeper/POWER.md b/context-keeper/POWER.md new file mode 100644 index 0000000..910fa08 --- /dev/null +++ b/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) diff --git a/context-keeper/hooks/capture-context.kiro.hook b/context-keeper/hooks/capture-context.kiro.hook new file mode 100644 index 0000000..f014a8c --- /dev/null +++ b/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." + } +} diff --git a/context-keeper/hooks/compress-context.kiro.hook b/context-keeper/hooks/compress-context.kiro.hook new file mode 100644 index 0000000..9836776 --- /dev/null +++ b/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." + } +} diff --git a/context-keeper/hooks/restore-context.kiro.hook b/context-keeper/hooks/restore-context.kiro.hook new file mode 100644 index 0000000..2c8b9a7 --- /dev/null +++ b/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." + } +} diff --git a/context-keeper/hooks/snapshot-context.kiro.hook b/context-keeper/hooks/snapshot-context.kiro.hook new file mode 100644 index 0000000..f6e0826 --- /dev/null +++ b/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." + } +} diff --git a/context-keeper/steering/capture-context.md b/context-keeper/steering/capture-context.md new file mode 100644 index 0000000..7e326b3 --- /dev/null +++ b/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. diff --git a/context-keeper/steering/compress-context.md b/context-keeper/steering/compress-context.md new file mode 100644 index 0000000..9512a22 --- /dev/null +++ b/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. diff --git a/context-keeper/steering/project-memory-update.md b/context-keeper/steering/project-memory-update.md new file mode 100644 index 0000000..253cc14 --- /dev/null +++ b/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. diff --git a/context-keeper/steering/restore-context.md b/context-keeper/steering/restore-context.md new file mode 100644 index 0000000..60e6f0f --- /dev/null +++ b/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. diff --git a/context-keeper/steering/snapshot-context.md b/context-keeper/steering/snapshot-context.md new file mode 100644 index 0000000..8dfcefb --- /dev/null +++ b/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`