claude-reflect

Claude Reflect

A 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.

What Is This?

By default, Claude Code does not carry rich project memory across sessions. Reflect runs fully locally alongside Claude Code's plugin system and adds:

• Persistent memory: Durable state lives in .subnotes/ by default, with canonical memory stored in the durable state's memory.json.
• Continuous reasoning: A long-running worker ingests transcript updates and maintains notes over time using Anthropic's SDK.
• Pattern learning: The autonomic pipeline logs observations, crystallizes patterns, promotes reflex rules, tracks intervention outcomes, and self-tunes.
• Real-time steering: PreToolUse can inject warnings, whispers, insights, asks, denies, or input corrections before a tool runs.
• 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.

Architecture

Claude Reflect currently has two cooperating parts: a continuous reflective worker and an autonomic control layer.

Continuous Reflect Worker

The continuous worker is started on SessionStart and fed transcript updates from UserPromptSubmit, PostToolUse, and mirrored Claude transcripts.

• Maintains canonical memory in the durable state's memory.json.
• Queues scored foreground notes in the durable state's conversation.json.
• Uses the memory block schema from Subconscious.af.
• Can use memory tools and, unless sdkToolsMode is off, conversation search, web, and local file-reading tools.

By default, the memory block set includes core_directives, guidance, pending_items, project_context, self_improvement, session_patterns, tool_guidelines, and user_preferences.

Autonomic Control Layer

The autonomic subsystem is split across five systems:

• System 1: Crystallizer: Converts observations into learned patterns in the durable state's autonomic/patterns.json.
• System 2: Reflex layer: Promotes patterns into reflex rules and matches them during PreToolUse.
• System 3: Intervention tracker: Records interventions and resolves whether they were followed, ignored, retried, or overridden.
• System 4: Self-tuner: Adjusts confidences and thresholds based on outcomes.
• System 5: Sentinel: Maintains fast, local counters for thrashing, test loops, error cascades, and overwrite risk.

Communication Style

Reflect 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.

Installation

Option 1: Claude Plugin Marketplace (Recommended)

1. Add the repository to your marketplace sources:

   /plugin marketplace add maddygoround/claude-reflect
   

2. Install the plugin:

   /plugin install claude-reflect
   

3. Enable the plugin:

   /plugin enable claude-reflect
   

   (To enable it globally for all projects: /plugin enable --global claude-reflect)

Option 2: Install Locally (From Source)

Requires Node 18+.

1. Clone the repo and install dependencies:

   git clone https://github.com/maddygoround/claude-reflect.git
   cd claude-reflect
   npm install
   

   (Or use bun install if you prefer.)
2. Add the local marketplace manifest:

   /plugin marketplace add ./.claude-plugin/marketplace.json
   

3. Install the plugin from that local marketplace entry:

   /plugin install claude-reflect
   

4. Enable the plugin:

   /plugin enable claude-reflect
   

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: mkdir -p ~/.claude/tmp && export TMPDIR="$HOME/.claude/tmp"

Configuration

Environment Variables and State Location

Reflect reads configuration from the durable state directory and falls back to a few environment variables:

export ANTHROPIC_API_KEY="your-api-key"  # Required unless set as anthropicApiKey in config.json
export EXA_API_KEY="your-exa-key"        # Optional: improves web_search results
export SUBNOTES_HOME="$HOME"             # Optional: relocate durable state out of the repo

• If SUBNOTES_HOME is unset, durable state lives in <repo>/.subnotes/.
• If SUBNOTES_HOME is set, durable state lives in {SUBNOTES_HOME}/.subnotes/<repo-namespace>/.
• This centralizes storage, but repositories stay isolated by namespace; it does not merge all repos into one shared memory file.