{"id":50133551,"url":"https://github.com/agynio/claude-map-reduce-memory","last_synced_at":"2026-05-28T10:32:55.257Z","repository":{"id":348332594,"uuid":"1195612838","full_name":"agynio/claude-map-reduce-memory","owner":"agynio","description":"Global, unlimited persistent memory for Claude Code agents. Context-activated hints injected   automatically via hooks using scatter-gather map-reduce.","archived":false,"fork":false,"pushed_at":"2026-04-15T15:14:23.000Z","size":163,"stargazers_count":23,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-15T15:35:12.684Z","etag":null,"topics":["agent-memory","ai-agents","claude","claude-code","cli","cmr-memory","llm","map-reduce","prompt-caching"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agynio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-03-29T21:46:41.000Z","updated_at":"2026-04-14T05:57:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agynio/claude-map-reduce-memory","commit_stats":null,"previous_names":["agynio/claude-map-reduce-memory"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/agynio/claude-map-reduce-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agynio%2Fclaude-map-reduce-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agynio%2Fclaude-map-reduce-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agynio%2Fclaude-map-reduce-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agynio%2Fclaude-map-reduce-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agynio","download_url":"https://codeload.github.com/agynio/claude-map-reduce-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agynio%2Fclaude-map-reduce-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33605378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"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":["agent-memory","ai-agents","claude","claude-code","cli","cmr-memory","llm","map-reduce","prompt-caching"],"created_at":"2026-05-23T21:00:29.590Z","updated_at":"2026-05-28T10:32:55.246Z","avatar_url":"https://github.com/agynio.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# cmr-memory\n\nPersistent, cross-session memory for Claude Code agents.\n\n## Overview\n\nWithout persistent memory, a Claude Code agent resets to zero every session — repeating the same mistakes, ignoring learned preferences, requiring the same rules re-prompted every time. Claude's built-in `MEMORY.md` is per-repo and read once at startup; notes fall off by position as the file grows, not by relevance.\n\n`cmr-memory` replaces that with context-activated retrieval. Notes are stored globally with a plain-language `--when` condition. Before every tool call, a PreToolUse hook reads the current transcript and runs retrieval against stored notes — using a small LLM that reasons about relevance rather than matching strings. Only hints that aren't already in the transcript are injected, so context stays bounded regardless of session length.\n\nAt scale, retrieval uses a map-reduce pattern: notes are split into fixed-size chunks and queried in parallel (one Haiku call per chunk) that makes it fast. Chunk system prompts are stable, so prompt caching keeps per-call cost low.\n\nEverything ships as a single npm CLI. No extra processes, no MCP servers. `cmr-memory init` registers the hooks, injects instructions into `CLAUDE.md`, and configures the retrieval model in one command.\n\n\n## Installation\n\n```bash\nnpm install -g @agynio/cmr-memory\ncmr-memory init --api-key sk-ant-...\n```\n\n## Authentication\n\n`cmr-memory` requires an API key for memory calls. Provide it with\nthe `--api-key` flag or the `ANTHROPIC_API_KEY` environment variable.\n\n```bash\ncmr-memory init --api-key sk-ant-...\n```\n\n```bash\nANTHROPIC_API_KEY=sk-ant-... cmr-memory init\n```\n\nConfigure or update the key later:\n\n```bash\ncmr-memory config --api-key sk-ant-...\n```\n\nRemove the key:\n\n```bash\ncmr-memory config --api-key off\n```\n\n## Usage\n\n### Agent-facing commands\n\nThese are called by the agent via the Bash tool.\n\n```bash\ncmr-memory write \"note content\" --when \"activation condition\"\n```\n\n```bash\ncmr-memory retrieve \"rate limiter config decisions\" --max 5\n```\n\n```bash\ncmr-memory list --limit 10\n```\n\n### User-facing commands\n\n```bash\ncmr-memory init --api-key sk-ant-...\ncmr-memory status\ncmr-memory config\ncmr-memory config --api-key sk-ant-...\ncmr-memory config --api-key off\ncmr-memory config --max-hints 5\ncmr-memory config --reminder on\ncmr-memory config --reminder off\ncmr-memory reset --confirm\ncmr-memory uninstall\n```\n\n## How It Works\n\n`cmr-memory` has four components:\n\n1. **CLI**: The binary used for writing, listing, and retrieving notes.\n2. **CLAUDE.md guidance**: Teaches the agent when to write or retrieve memory.\n3. **PreToolUse hook**: Reads the transcript and upcoming tool call,\n   runs scatter-gather retrieval across chunk files, and injects only\n   NEW `[MEMORY]` hints via deduplication.\n4. **PostToolUse hook**: Optional static reminder to consider writing\n   memory after tool calls.\n\nRetrieval uses a scatter-gather approach (one call per chunk), then\ndeduplicates against existing `[MEMORY]` hints in the transcript so\ncontext size stays bounded as tool calls accumulate.\n\n## Configuration\n\nConfig file: `~/.claude-memory/config.json`.\n\n- **API key**: `cmr-memory config --api-key sk-ant-...`\n- **Disable API key**: `cmr-memory config --api-key off`\n- **Max hints**: `cmr-memory config --max-hints 5`\n- **Reminder toggle**: `cmr-memory config --reminder on|off`\n\n`--reminder off` removes the PostToolUse hook entry from\n`~/.claude/settings.json`; `--reminder on` adds it back.\n\n## Data Model\n\nData lives in `~/.claude-memory/`:\n\n```\n~/.claude-memory/\n  config.json\n  state.json\n  chunks/\n    chunk-001.json\n    chunk-002.json\n```\n\nNotes are stored in chunk JSON files with content, activation `when`,\nand timestamps. New notes append to the latest chunk until it reaches\nthe token limit, then a new chunk file is created.\n\n## Error Handling\n\nThe hooks never block the agent. Errors return empty hook output and\nlog to stderr. CLI commands surface errors to the terminal and exit\nnon-zero so the agent can react.\n\n## Uninstall\n\n```bash\ncmr-memory uninstall\n```\n\nThis removes the hooks, memory instructions from\n`~/.claude/CLAUDE.md`, optionally deletes `~/.claude-memory/`, and\nuninstalls the global CLI.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagynio%2Fclaude-map-reduce-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagynio%2Fclaude-map-reduce-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagynio%2Fclaude-map-reduce-memory/lists"}