{"id":48333558,"url":"https://github.com/maddygoround/claude-reflect","last_synced_at":"2026-04-05T01:34:58.051Z","repository":{"id":347489165,"uuid":"1193633242","full_name":"maddygoround/claude-reflect","owner":"maddygoround","description":"Subconscious memory for Claude agents ","archived":false,"fork":false,"pushed_at":"2026-03-30T02:47:23.000Z","size":6344,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-05T01:34:56.429Z","etag":null,"topics":["agents","agents-sdk","claude","hooks","memory","plugin"],"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/maddygoround.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-27T12:35:01.000Z","updated_at":"2026-03-30T02:47:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maddygoround/claude-reflect","commit_stats":null,"previous_names":["maddygoround/claude-subnotes","maddygoround/claude-reflect"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/maddygoround/claude-reflect","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maddygoround%2Fclaude-reflect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maddygoround%2Fclaude-reflect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maddygoround%2Fclaude-reflect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maddygoround%2Fclaude-reflect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maddygoround","download_url":"https://codeload.github.com/maddygoround/claude-reflect/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maddygoround%2Fclaude-reflect/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31421869,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T00:25:07.052Z","status":"ssl_error","status_checked_at":"2026-04-05T00:25:05.923Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agents","agents-sdk","claude","hooks","memory","plugin"],"created_at":"2026-04-05T01:34:55.197Z","updated_at":"2026-04-05T01:34:58.043Z","avatar_url":"https://github.com/maddygoround.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Reflect\n\nA persistent, local background agent for Claude Code. Claude Reflect watches your sessions, maintains durable notes, learns from repeated patterns, and surfaces timely steer/insight messages back into Claude.\n\n![evil claude](assets/evil-claude.png)\n\n## What Is This?\n\nBy default, Claude Code does not carry rich project memory across sessions. Reflect runs fully locally alongside Claude Code's plugin system and adds:\n\n- **Persistent memory**: Durable state lives in `.subnotes/` by default, with canonical memory stored in the durable state's `memory.json`.\n- **Continuous reasoning**: A long-running worker ingests transcript updates and maintains notes over time using Anthropic's SDK.\n- **Pattern learning**: The autonomic pipeline logs observations, crystallizes patterns, promotes reflex rules, tracks intervention outcomes, and self-tunes.\n- **Real-time steering**: `PreToolUse` can inject warnings, whispers, insights, asks, denies, or input corrections before a tool runs.\n- **Distilled context sync**: Reflect keeps a distilled section synced into `CLAUDE.md` or `.claude/CLAUDE.md` while also injecting targeted context directly through hook output.\n\n## Architecture\n\nClaude Reflect currently has two cooperating parts: a continuous reflective worker and an autonomic control layer.\n\n### Continuous Reflect Worker\n\nThe continuous worker is started on `SessionStart` and fed transcript updates from `UserPromptSubmit`, `PostToolUse`, and mirrored Claude transcripts.\n\n- Maintains canonical memory in the durable state's `memory.json`.\n- Queues scored foreground notes in the durable state's `conversation.json`.\n- Uses the memory block schema from `Subconscious.af`.\n- Can use memory tools and, unless `sdkToolsMode` is `off`, conversation search, web, and local file-reading tools.\n\nBy default, the memory block set includes `core_directives`, `guidance`, `pending_items`, `project_context`, `self_improvement`, `session_patterns`, `tool_guidelines`, and `user_preferences`.\n\n### Autonomic Control Layer\n\nThe autonomic subsystem is split across five systems:\n\n- **System 1: Crystallizer**: Converts observations into learned patterns in the durable state's `autonomic/patterns.json`.\n- **System 2: Reflex layer**: Promotes patterns into reflex rules and matches them during `PreToolUse`.\n- **System 3: Intervention tracker**: Records interventions and resolves whether they were followed, ignored, retried, or overridden.\n- **System 4: Self-tuner**: Adjusts confidences and thresholds based on outcomes.\n- **System 5: Sentinel**: Maintains fast, local counters for thrashing, test loops, error cascades, and overwrite risk.\n\n### Communication Style\n\nReflect is programmed via `Subconscious.af` to stay concise, observational, and useful. Foreground notes are rendered to the user as `Notes reflect`, `Notes steer`, or `Notes insight` rather than hidden internal logs.\n\n## Installation\n\n### Option 1: Claude Plugin Marketplace (Recommended)\n\n1. **Add the repository to your marketplace sources:**\n   ```bash\n   /plugin marketplace add maddygoround/claude-reflect\n   ```\n2. **Install the plugin:**\n   ```bash\n   /plugin install claude-reflect\n   ```\n3. **Enable the plugin:**\n   ```bash\n   /plugin enable claude-reflect\n   ```\n   *(To enable it globally for all projects: `/plugin enable --global claude-reflect`)*\n\n### Option 2: Install Locally (From Source)\n\nRequires Node 18+.\n\n1. **Clone the repo and install dependencies:**\n   ```bash\n   git clone https://github.com/maddygoround/claude-reflect.git\n   cd claude-reflect\n   npm install\n   ```\n   *(Or use `bun install` if you prefer.)*\n2. **Add the local marketplace manifest:**\n   ```bash\n   /plugin marketplace add ./.claude-plugin/marketplace.json\n   ```\n3. **Install the plugin from that local marketplace entry:**\n   ```bash\n   /plugin install claude-reflect\n   ```\n4. **Enable the plugin:**\n   ```bash\n   /plugin enable claude-reflect\n   ```\n\n\u003e **Linux Note (tmpfs workaround):** If installation or runtime fails with `EXDEV: cross-device link not permitted` (common when `/tmp` is on a different filesystem), set `TMPDIR` first:\n\u003e `mkdir -p ~/.claude/tmp \u0026\u0026 export TMPDIR=\"$HOME/.claude/tmp\"`\n\n## Configuration\n\n### Environment Variables and State Location\n\nReflect reads configuration from the durable state directory and falls back to a few environment variables:\n\n```bash\nexport ANTHROPIC_API_KEY=\"your-api-key\"  # Required unless set as anthropicApiKey in config.json\nexport EXA_API_KEY=\"your-exa-key\"        # Optional: improves web_search results\nexport SUBNOTES_HOME=\"$HOME\"             # Optional: relocate durable state out of the repo\n```\n\n- If `SUBNOTES_HOME` is unset, durable state lives in `\u003crepo\u003e/.subnotes/`.\n- If `SUBNOTES_HOME` is set, durable state lives in `{SUBNOTES_HOME}/.subnotes/\u003crepo-namespace\u003e/`.\n- This centralizes storage, but repositories stay isolated by namespace; it does not merge all repos into one shared memory file.\n\n### Configuration (`config.json` in the durable state directory)\n\nOn first run, Reflect creates `config.json` in the durable state directory and merges in any missing defaults on later runs.\n\nAbridged example:\n\n```json\n{\n  \"mode\": \"whisper\",\n  \"sdkToolsMode\": \"read-only\",\n  \"architecture\": \"continuous\",\n  \"autonomic\": true,\n  \"debug\": false,\n  \"checkIntervalMs\": 1000,\n  \"minMessages\": 1,\n  \"idleTimeoutMs\": 1800000,\n  \"maxContinuations\": 2,\n  \"crystallizeInterval\": 10,\n  \"minObservations\": 5,\n  \"anthropicModel\": \"claude-sonnet-4-6\",\n  \"crystallizerModel\": \"claude-haiku-3-5-20250815\"\n}\n```\n\n- `mode`: `whisper` keeps the distilled `CLAUDE.md` section and targeted hook messages active without dumping full memory on every prompt. `full` injects the full memory snapshot on the first prompt, then changed blocks on later syncs. `off` disables Reflect.\n- `sdkToolsMode`: accepts `read-only`, `full`, or `off`. In the current code, any value other than `off` enables the worker's conversation, web, and local file-reading tools.\n- `autonomic`: enables the autonomic systems and sentinel warnings.\n- `debug`: turns on verbose hook logging.\n- `anthropicModel`: model used by the main continuous reasoning worker.\n- `crystallizerModel`: model used when System 1 names and describes newly discovered patterns.\n- `projectDir`: optional override for where the distilled `CLAUDE.md` section is synced.\n- `anthropicApiKey` and `exaApiKey`: optional config-file equivalents of `ANTHROPIC_API_KEY` and `EXA_API_KEY`.\n- Additional sentinel, crystallizer, and self-tuner thresholds are also persisted in the same file.\n\n## Hook Lifecycle\n\nClaude Reflect is wired through Claude Code hooks:\n\n| Hook | Purpose |\n|------|---------|\n| `SessionStart` | Ensures config exists, syncs distilled state into `CLAUDE.md`, initializes session state, and starts the continuous worker. |\n| `UserPromptSubmit` | Mirrors new user input into the internal transcript and optionally injects full memory or foreground notes. |\n| `PreToolUse` | Syncs memory/message updates and runs sentinel + reflex gating. It can pass, whisper, insight, ask, deny, or correct before the tool executes. |\n| `PostToolUse` | Streams tool events into the transcript and updates sentinel counters. |\n| `Stop` | If unread foreground notes exist, blocks stop long enough for Claude to surface them visibly as `Notes reflect`, `Notes steer`, or `Notes insight`. |\n| `SessionEnd` | Stops the continuous worker and cleans up stale worker artifacts. |\n\n## State and Logs\n\n### Durable State\n\nCanonical state lives in the durable state directory (`\u003crepo\u003e/.subnotes/` by default, or `$SUBNOTES_HOME/.subnotes/\u003crepo-namespace\u003e/` when relocated).\n\n- `config.json` - runtime configuration\n- `memory.json` - canonical memory blocks\n- `conversation.json` - queued foreground notes for Claude\n- `session-\u003crepo-namespace\u003e-\u003csession-id\u003e.json` - per-session sync state\n- `transcript-\u003crepo-namespace\u003e-\u003csession-id\u003e.jsonl` - mirrored transcript stream\n- `autonomic/patterns.json` - learned patterns\n- `autonomic/reflexes.json` - promoted reflex rules\n- `autonomic/interventions.json` - recorded intervention outcomes\n- `autonomic/meta-config.json` - self-tuned thresholds and style data\n- `autonomic/observations.jsonl` - append-only observation log\n\n### Logs and Ephemeral State\n\nLogs, worker PID files, and sentinel state live under `path.join(os.tmpdir(), \"subnotes-sync-\u003cuid\u003e\")`.\n\n- On many Linux systems this is `/tmp/subnotes-sync-$(id -u)/`\n- On macOS it is usually under `/var/folders/.../subnotes-sync-\u003cuid\u003e/`\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaddygoround%2Fclaude-reflect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaddygoround%2Fclaude-reflect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaddygoround%2Fclaude-reflect/lists"}