{"id":43952286,"url":"https://github.com/swannysec/context-keeper","last_synced_at":"2026-02-15T04:07:29.929Z","repository":{"id":333935032,"uuid":"1138550820","full_name":"swannysec/context-keeper","owner":"swannysec","description":"Text file based memory plugin for AI agents","archived":false,"fork":false,"pushed_at":"2026-02-07T02:36:47.000Z","size":109,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-07T13:20:28.837Z","etag":null,"topics":["ai-memory","ai-skills","claude-code","codex","copilot","cursor","windsurf","zed"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swannysec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-20T20:23:00.000Z","updated_at":"2026-02-07T02:36:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/swannysec/context-keeper","commit_stats":null,"previous_names":["swannysec/context-keeper"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/swannysec/context-keeper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swannysec%2Fcontext-keeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swannysec%2Fcontext-keeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swannysec%2Fcontext-keeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swannysec%2Fcontext-keeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swannysec","download_url":"https://codeload.github.com/swannysec/context-keeper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swannysec%2Fcontext-keeper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29468393,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T01:01:38.065Z","status":"online","status_checked_at":"2026-02-15T02:00:07.449Z","response_time":118,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","ai-skills","claude-code","codex","copilot","cursor","windsurf","zed"],"created_at":"2026-02-07T04:02:48.926Z","updated_at":"2026-02-15T04:07:29.917Z","avatar_url":"https://github.com/swannysec.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ConKeeper (context-keeper)\n\nA file-based agent memory system for AI coding assistants that provides structured context management using plain Markdown files.\n\n**Multi-Platform Support:** ConKeeper works with Claude Code, GitHub Copilot, OpenAI Codex, Cursor, Windsurf, and Zed.\n\n## Overview\n\nConKeeper replaces database-backed context management with simple, version-controllable Markdown files. It provides:\n\n- **Global memory** (`~/.claude/memory/`) - Cross-project preferences and patterns\n- **Project memory** (`\u003cproject\u003e/.claude/memory/`) - Project-specific context, decisions, and progress\n- **SessionStart hook** - Automatic memory awareness at session start\n- **Context preservation hooks** - Automatic memory-sync before context compaction\n- **Skills + commands** - Easy memory initialization, sync, and session handoff\n- **Category tags** - Structured `\u003c!-- @category: ... --\u003e` tags for filtering and search\n- **Privacy tags** - `\u003cprivate\u003e` blocks and file-level privacy for sensitive content\n- **Observation hook** - Automatic tool usage logging via PostToolUse hook\n- **Correction detection** - Real-time detection of user corrections and friction signals\n- **Session retrospection** - After Action Review workflow via `/memory-reflect`\n- **Facets integration** - Claude Code session analytics for friction and satisfaction trends\n\n## Installation\n\n### Option 1: Marketplace (Recommended)\n\nAdd the marketplace and install the plugin:\n\n```bash\n# Add the marketplace (use full HTTPS URL to avoid SSH auth issues)\n/plugin marketplace add https://github.com/swannysec/context-keeper.git\n\n# Install the plugin\n/plugin install context-keeper@swannysec-plugins\n\n# Create global memory directory\nmkdir -p ~/.claude/memory\n```\n\n\u003e **Note:** Using the full HTTPS URL avoids [SSH authentication issues](https://github.com/anthropics/claude-code/issues/14485) with the `github` source type.\n\n### Option 2: Manual Installation\n\n1. Clone or symlink this repo to `~/.claude/plugins/context-keeper`:\n   ```bash\n   # Use absolute path for reliable symlink (not relative)\n   ln -s /absolute/path/to/context-keeper ~/.claude/plugins/context-keeper\n   ```\n\n2. Enable the plugin in `~/.claude/settings.json`:\n   ```json\n   {\n     \"enabledPlugins\": {\n       \"context-keeper\": true\n     }\n   }\n   ```\n\n3. Create global memory directory:\n   ```bash\n   mkdir -p ~/.claude/memory\n   ```\n\n## Multi-Platform Support\n\nConKeeper supports multiple AI coding platforms through native skills and AGENTS.md awareness.\n\n### Platform Support Matrix\n\n| Platform | Support Type | Status |\n|----------|--------------|--------|\n| **Claude Code** | Native Plugin | ✅ Fully Tested |\n| **GitHub Copilot in VSCode** | Native Skills | ✅ Verified |\n| **OpenAI Codex** | Native Skills | ⚠️ Documented |\n| **Cursor** | Native Skills (Nightly) | ⚠️ Documented |\n| **Windsurf** | .windsurfrules | ⚠️ Documented |\n| **Zed** | AGENTS.md + Rules | ✅ Verified |\n\n### Quick Setup (Any Platform)\n\nAdd this snippet to your project's AGENTS.md:\n\n```text\n\u003c!-- ConKeeper Memory System --\u003e\n## Memory System\n\nThis project uses ConKeeper for persistent AI context management.\n\n**Memory Location:** `.claude/memory/` (or `.ai/memory/`)\n\n**Available Workflows:**\n- **memory-init** - Initialize memory for this project\n- **memory-sync** - Sync session state to memory files\n- **session-handoff** - Generate handoff for new session\n- **memory-search** - Search memory files by keyword or category\n- **memory-reflect** - Session retrospection and improvement analysis\n- **memory-insights** - Session friction trends and success pattern analysis\n\n**Memory Files:**\n- `active-context.md` - Current focus and state\n- `product-context.md` - Project overview\n- `progress.md` - Task tracking\n- `decisions/` - Architecture Decision Records\n- `sessions/` - Session summaries\n\n**Usage:**\n- Load memory at session start for non-trivial tasks\n- Sync memory after significant progress\n- Use handoff when context window fills\n\nFor full documentation: https://github.com/swannysec/context-keeper\n\u003c!-- /ConKeeper --\u003e\n```\n\n### Interactive Installer\n\n```bash\n# Run from your project directory\n/path/to/context-keeper/tools/install.sh\n```\n\n### Platform-Specific Setup\n\nSee [docs/platform-guides/](docs/platform-guides/) for detailed platform instructions:\n- [Claude Code](docs/platform-guides/claude-code.md)\n- [GitHub Copilot](docs/platform-guides/copilot.md)\n- [OpenAI Codex](docs/platform-guides/codex.md)\n- [Cursor](docs/platform-guides/cursor.md)\n- [Windsurf](docs/platform-guides/windsurf.md)\n- [Zed](docs/platform-guides/zed.md)\n\n## Usage\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `/memory-init` | Initialize memory for current project |\n| `/memory-sync` | Sync current session state to memory files |\n| `/session-handoff` | Generate handoff prompt for new session |\n| `/memory-search` | Search memory files by keyword or category |\n| `/memory-config` | View and modify ConKeeper configuration |\n| `/memory-reflect` | Session retrospection using After Action Review methodology |\n| `/memory-insights` | Analyze session friction trends and success patterns (Claude Code) |\n\n### Memory Structure\n\n```\n~/.claude/memory/                    # Global (cross-project)\n├── preferences.md                   # Tool/workflow preferences\n├── patterns.md                      # Reusable patterns\n└── glossary.md                      # Personal terminology\n\n\u003cproject\u003e/.claude/memory/            # Project-specific\n├── product-context.md               # Project overview, architecture\n├── active-context.md                # Current focus, recent decisions\n├── progress.md                      # Task tracking\n├── patterns.md                      # Project conventions\n├── glossary.md                      # Project terminology\n├── decisions/                       # ADRs (ADR-001-title.md)\n└── sessions/                        # Session history\n```\n\n### Workflow\n\n1. **Start a new project:** Run `/memory-init` to create memory structure\n2. **During work:** Memory updates happen naturally via suggestions or explicit `/memory-sync`\n3. **End of session:** Run `/session-handoff` to generate a continuation prompt\n4. **Next session:** Paste the handoff prompt to resume seamlessly\n\n## Context Preservation (Claude Code)\n\nConKeeper automatically preserves your memory before context window compaction. Two hooks monitor usage and escalate:\n\n| Context % | Action |\n|-----------|--------|\n| \u003c 60% | Normal operation |\n| \u003e= 60% | Auto memory-sync (no approval needed, fires once) |\n| \u003e= 80% | Hard block — requires manual `/memory-sync` before continuing |\n| \u003e= 90% | Claude's auto-compaction fires; PreCompact hook warns if unsaved |\n\n### Recommended Setup\n\nFor the full escalation sequence, add to your shell profile (`.zshrc`, `.bashrc`, etc.):\n\n```bash\nexport CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=90\n```\n\nThis pushes Claude's built-in compaction to 90%, giving ConKeeper's hooks room at 60% and 80%.\n\n### Configuration\n\nThresholds are configurable per-project in `.claude/memory/.memory-config.md`:\n\n```yaml\n---\nsuggest_memories: true        # Whether to suggest memory additions (default: true)\nauto_load: true               # Auto-load memory at session start (default: true)\noutput_style: normal          # quiet | normal | explanatory (default: normal)\ntoken_budget: standard        # economy | light | standard | detailed (default: standard)\nauto_sync_threshold: 60       # When to auto-sync (default: 60)\nhard_block_threshold: 80      # When to block until manual sync (default: 80)\n# context_window_tokens: 200000 # Override auto-detection (auto-detects from model)\nobservation_hook: true        # Enable/disable PostToolUse observation logging (default: true)\nobservation_detail: full      # full | stubs_only | off (default: full)\ncorrection_sensitivity: low   # low | medium — correction detection sensitivity (default: low)\nauto_reflect: true            # Auto-trigger /memory-reflect after /memory-sync (default: true)\n---\n```\n\nAdjust via `/memory-config` or edit the file directly.\n\n### Requirements\n\nThe context preservation hooks require `jq` and `bc`. Install via your package manager if not already present. Hooks exit gracefully if either is missing.\n\n## Design Principles\n\n- **Files are sufficient** - All memory in `.md` files; no database\n- **Quiet by default** - Memory operations summarized to 1-2 lines\n- **Graceful degradation** - Works without hooks via CLAUDE.md instructions\n- **User control** - Memory suggestions can be disabled per-project\n- **Simple over complex** - Standard filesystem; no special tooling\n\n## Security Considerations\n\nMemory files may contain project context that influences AI assistant behavior. For security guidance, see [SECURITY.md](SECURITY.md).\n\nKey recommendations:\n- Add `.claude/memory/` to `.gitignore` for shared repositories\n- Review memory files when working on untrusted codebases\n- See SECURITY.md for prompt injection awareness\n\n## Token Efficiency\n\nMemory files use concise conventions:\n- Bullet points over paragraphs (30-50% fewer tokens)\n- Terse headers\n- No redundant boilerplate\n- Active voice, present tense\n- Abbreviations when clear (DB, auth, etc.)\n\n**Target sizes:**\n- product-context.md: ~500-1000 tokens\n- active-context.md: ~300-500 tokens\n- progress.md: ~200-500 tokens\n- ADRs: ~500 tokens each\n\n## Acknowledgments\n\nConKeeper was inspired by [ContextPortal](https://github.com/GreatScottyMac/context-portal) by [GreatScottyMac](https://github.com/GreatScottyMac). ContextPortal pioneered the concept of structured memory bank files for AI context persistence, and ConKeeper builds on those ideas with a Claude Code plugin implementation.\n\n## License\n\nApache License 2.0 with Commons Clause - See [LICENSE](LICENSE) for details.\n\nYou may freely use, modify, and distribute this software. The Commons Clause restricts selling the software itself as a commercial product or service.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswannysec%2Fcontext-keeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswannysec%2Fcontext-keeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswannysec%2Fcontext-keeper/lists"}