2230 Compound Engineering Supermemory Integration Fae26a48

Integrating Compound Engineering + Supermemory into the Halt Agent Harness

Date: 2026-01-30 Method: /heavy multi-perspective analysis (12 Opus agents, 4 rounds) Repos analyzed: compound-engineering-plugin (6.2k stars), claude-supermemory Status: Research complete. Implementation not started.

Executive Summary

Two open-source projects solve the same fundamental problem: Claude Code sessions don't learn from each other. Each session starts from scratch, re-discovering problems that previous sessions already solved. The git history of this very toolkit proves the cost: 13 incremental commits discovering auto-approval edge cases one-by-one, and a 473-line PID-scoping feature built with "high confidence" then entirely deleted 25 minutes later -- with no record of WHY it failed.

The integration opportunity is real but narrower than it appears. After 5 parallel Opus agents, an adversarial dialogue, and red-team stress testing, the analysis converged on a local-first approach: ~340 lines of new code across 5 files, no cloud dependencies, no npm packages. From compound-engineering's 28 agents + 24 commands + 15 skills, we need exactly one technique: the Compound step (structured knowledge capture). From supermemory's 4 hooks + cloud API, we need the concept of cross-session memory injection but implemented locally.

Table of Contents

• Source Repository Analysis
• What Each Repo Contributes
• Recommended Approach
• Implementation Tradeoffs
• Blocking Issues
• Concrete Implementation
• Risk Mitigations
• Future Phases
• Multi-Agent Analysis Details

Source Repository Analysis

compound-engineering-plugin (Every Inc)

Repository: https://github.com/EveryInc/compound-engineering-plugin (6.2k stars, 492 forks, 153 commits)

What it is: A Claude Code plugin marketplace implementing a complete software development methodology where AI agents handle planning, implementation, review, and knowledge capture in a self-improving loop.

Core philosophy: "Each unit of engineering work should make subsequent units easier -- not harder." Traditional development accumulates technical debt. Compound engineering inverts this by creating a compounding knowledge loop where learnings from each cycle feed into the next.

Architecture:

The Four-Step Loop:

Plan --> Work --> Review --> Compound --> (repeat)

1. Plan (/workflows:plan): Transform feature descriptions into detailed implementation plans. AI agents research the codebase, external docs, and institutional learnings.
2. Work (/workflows:work): Execute the plan systematically -- create a branch/worktree, break the plan into tasks, implement, test, commit, PR.
3. Review (/workflows:review): Multi-agent code review using 13+ parallel agents (security, performance, architecture, patterns, simplicity, etc.). Findings categorized by severity (P1/P2/P3).
4. Compound (/workflows:compound): Document the recently solved problem. Parallel sub-agents extract problem context, solution, prevention strategies, cross-references, and category, then write a structured markdown file to docs/solutions/.

Key techniques:

• Institutional knowledge capture: The Compound step writes structured learnings to docs/solutions/ with YAML frontmatter (problem_type, module, symptoms, root_cause, severity, tags). A learnings-researcher agent searches these before new work begins.
• Massive parallelism: /workflows:review launches 13+ review agents simultaneously. /deepen-plan spawns 40+ parallel agents.
• Agent-native architecture philosophy: Parity (agents can do anything users can), granularity (atomic primitives), composability (new features = new prompts), emergent capability.
• Specialized review personas: dhh-rails-reviewer, security-sentinel, performance-oracle, etc.
• Dynamic skill discovery: Commands dynamically find all installed skills and spawn sub-agents per relevant skill.
• Cross-platform CLI: Bun/TypeScript CLI converts Claude Code plugins to OpenCode and Codex formats.

Key articles:

• "Compound Engineering: How Every Codes With Agents" (Dan Shipper & Kieran Klaassen, Dec 2025) -- foundational article
• "Agent-native Architectures" (Dan Shipper, Jan 2026) -- the philosophy behind the plugin
• "Learning from Every's Compound Engineering" (Will Larson, Jan 2026) -- practitioner analysis calling "Compound" the most innovative step

claude-supermemory (Supermemory AI)

Repository: https://github.com/supermemoryai/claude-supermemory (66 stars, 3 forks)

What it is: A Claude Code plugin that gives Claude persistent memory across sessions using the Supermemory cloud API. Built by Supermemory (founded by Dhravya Shah), which positions itself as a "Universal Memory API for AI apps."

Architecture:

Hook lifecycle:

1. SessionStart (context-hook.cjs): Calls Supermemory profile API. Returns static facts (persistent preferences) and dynamic facts (recent context). Injects as <supermemory-context> block via additionalContext.
2. UserPromptSubmit (prompt-hook.cjs): Currently a no-op stub.
3. PostToolUse (observation-hook.cjs): Currently a no-op stub, triggered for Edit|Write|Bash|Task.
4. Stop (summary-hook.cjs): Reads JSONL transcript, formats user/assistant messages + tool use, strips system reminders, sends to Supermemory add API with project-scoped containerTag.

Key techniques:

• Project-scoped memory isolation: containerTag from SHA-256 of git root path (e.g., claudecode_project_a1b2c3d4...).
• Auto-maintained user profile: Static facts (persistent preferences) + dynamic facts (recent context), evolving automatically.
• Semantic search + hybrid retrieval: Vector + keyword search with similarity scores.
• Transcript compression: Tool observations compressed to one-line summaries (Edit -> "Edited file.py: old -> new"). Read tool results skipped entirely.
• Incremental capture: Tracks last captured UUID per session, only sends new content.
• Content sanitization: Strips <system-reminder> and <supermemory-context> tags to prevent recursive injection.
• Authentication: Environment variable, credentials file, or browser-based OAuth flow (local HTTP server on port 19876).

Comparison to CLAUDE.md:

What Each Repo Contributes

From compound-engineering-plugin

From claude-supermemory

Recommended Approach

Build 3 Components (~340 lines)

How Knowledge Compounds

Session A solves auth bug
        |
        v
User runs /compound --> writes docs/solutions/runtime-errors/auth-token-refresh-20260130.md
        |
        v
Session B starts --> compound-context-loader.py injects: "1 past solution matching recent commits"
        |
        v
Session B runs /build --> Phase 0.5 greps docs/solutions/ --> finds auth solution
        |
        v
Session B avoids re-discovering the auth bug. Saves 10-30 minutes.
        |
        v
Session B solves a different problem --> /compound captures it
        |
        v
Each session makes the next session smarter.

Why NOT Supermemory Cloud Integration

The Critical Reviewer identified 10 implementation risks with direct Supermemory integration. The top 3:

1. Stop hook race condition (HIGH): Halt's stop-validator.py blocks sessions via exit code 2. Supermemory's summary-hook.cjs runs in parallel and uploads transcripts even on blocked stops, creating duplicate memory entries (2-4x per autonomous session).

2. Sensitive code exfiltration (HIGH): transcript-formatter.js includes file edits, bash commands, and tool results with only 200-500 char truncation and zero secret filtering. Every git diff, psql output, and .env read gets sent to a third-party cloud API.

3. 30s SessionStart timeout (HIGH): context-hook.cjs makes a network call to api.supermemory.ai on every session start. The October 2025 incident report documents a 28-minute degradation with cascading retry amplification. During such periods, every session start takes the full 30s timeout.

The local approach captures 80% of the value at 5% of the complexity, with zero operational risk.

Implementation Tradeoffs

Tradeoff 1: Where Do Solution Files Live?

Recommendation: Target project. Cross-project learning is a Phase 2 optimization. The immediate value is preventing the same project from re-discovering its own problems.

Tradeoff 2: Automatic vs Manual Triggering

Recommendation: Start manual (/compound), add a prompt in /build Phase 3 that says "If the fix was non-trivial, run /compound to capture this learning." Human-in-the-loop for quality control.

Tradeoff 3: Retrieval Strategy

Recommendation: Grep for the hook (deterministic, fast), LLM-mediated search in /build Phase 0.5 (Claude reads matching files and reasons about relevance). Two-tier approach matching halt's existing pattern: hooks do mechanical work, skills do intelligent work.

Blocking Issues

The red-team identified 3 issues that must be resolved before coding:

1. Grep Regex Bug (BLOCKING)

The proposed grep -ri "tags:.*[keyword]" pattern treats [keyword] as a regex character class, matching any file containing any single letter from the keyword. Every query returns every file.

Testing: grep -ri "tags:.*[auth]" matches a line with tags: [database, caching, redis] because a is in "database".

Fix: Use grep -riwl "keyword" docs/solutions/ (word-match, files-only) for the hook, and grep -ri "tags:.*\bkeyword\b" for tag-specific searches.

2. No Auto-Trigger for /compound (BLOCKING)

Without automatic triggering, the knowledge base depends entirely on the user remembering to type /compound. It won't populate.

Fix: Add a line to /build's Phase 3 (completion): "If the task required debugging or non-trivial investigation, capture the learning with /compound." Also add to the stop-validator's checklist prompt.

3. SessionStart Injects Recent, Not Relevant (MEDIUM)

The hook injects the 5 most recent solutions regardless of the current task. If you fixed CSS yesterday and are debugging auth today, the CSS solution wastes context tokens.

Fix: The hook extracts keywords from recent git commit subjects (proxy for current work area) and greps for matching solutions alongside recent ones. The deep-dive implementation includes this dual strategy (_get_recent_solutions + _grep_solutions with _get_git_keywords).

Concrete Implementation

File 1: /compound Skill

Path: config/skills/compound/SKILL.md

The skill captures solved problems as structured markdown. Workflow:

1. Extract context from the current session (problem, investigation, root cause, solution, prevention)
2. Classify with YAML frontmatter against a defined schema (problem_type, component, root_cause, resolution_type, severity, symptoms, tags)
3. Determine file path: docs/solutions/{category}/{slug}-{YYYYMMDD}.md
4. Write the document with structured sections: Problem, Symptoms, What Didn't Work, Root Cause, Solution, Why This Works, Prevention, Related
5. Confirm with path and tags for searchability

Triggers: /compound, "document this solution", "capture this learning"

File 2: YAML Schema Reference

Path: config/skills/compound/references/solution-schema.md

Defines the controlled vocabulary:

• 11 problem types (mapped to category directories): build_error, test_failure, runtime_error, performance_issue, config_error, dependency_issue, integration_issue, logic_error, design_flaw, infrastructure_issue, security_issue
• 16 root causes: missing_config, wrong_api_usage, race_condition, state_management, missing_validation, missing_dependency, wrong_assumption, incomplete_migration, environment_mismatch, logic_error, type_error, schema_mismatch, memory_issue, timeout, permission_error, platform_difference
• 10 resolution types: code_fix, config_change, dependency_update, architecture_change, test_fix, environment_fix, workaround, documentation, rollback, deletion
• 4 severity levels: critical, high, medium, low

File 3: Context Injection Hook

Path: config/hooks/compound-context-loader.py

SessionStart hook (~140 lines) that:

1. Finds docs/solutions/ in the project directory
2. Gets 5 most recent solutions (by mtime)
3. Extracts keywords from recent git commit subjects
4. Greps for keyword-matched solutions (3 max)
5. Outputs a concise summary: total count, recent list with tags, keyword-matched list
6. Registered in settings.json after read-docs-reminder.py with 5s timeout

File 4: Build Skill Modification

Path: config/skills/build/SKILL.md (edit)

Adds ~7 lines to Phase 0.5 Step 2 ("Explore the codebase first"):

- **Past solutions** (if `docs/solutions/` exists):
  grep -r -l -i "[task-relevant-keyword]" docs/solutions/
  Read any matching files -- they contain root causes, failed attempts,
  and prevention guidance from previous sessions.

File 5: Settings Registration

Path: config/settings.json (edit)

Adds the new hook to both SessionStart groups (default and compact matcher):

{
  "type": "command",
  "command": "python3 \"$HOME/.claude/hooks/compound-context-loader.py\"",
  "timeout": 5
}

Example Solution Document

Based on the real PID-scoping failure in this repo's history:

---
title: "macOS basename breaks PID-scoped state file paths"
date: 2026-01-30
problem_type: runtime_error
component: "hooks/_common.py _get_ancestor_pid()"
root_cause: platform_difference
resolution_type: deletion
severity: high
symptoms:
  - "PID-scoped state files not found on macOS"
  - "Auto-approval hooks fail silently"
  - "Works on Linux, fails on macOS"
tags: [hooks, macos, pid, basename, platform, state-files]
---

# macOS basename breaks PID-scoped state file paths

## Problem
PID-scoped state isolation silently failed on macOS because
_get_ancestor_pid() used basename on /proc/-style paths that
don't exist on macOS.

## What Didn't Work
**Attempt 1:** Added fallback path for /proc/ not existing
- Why: The basename call itself was the problem, not the path lookup

**Attempt 2:** Used psutil for cross-platform process info
- Why: Violated the "no new dependencies" constraint

## Root Cause
ps -o comm= returns different formats on Linux vs macOS.
Linux: /usr/bin/python3 (full path). macOS: python3 (name only).
basename() on a name without path separators strips incorrectly.

## Solution
Entire PID-scoping approach was deleted (473 lines). Replaced with
simpler session_id-based isolation via git worktrees.

## Prevention
- Process inspection APIs behave differently across platforms
- Test hooks on both macOS and Linux before merging
- Prefer session_id isolation over PID-based isolation

Risk Mitigations

Future Phases

Multi-Agent Analysis Details

Method

This report was produced using /heavy (multi-perspective analysis) with the following agent structure:

*AGI-Pilled agent failed with API encoding error.

Mode: Implementation

The user stated: "I am not looking for contrarian takes, this is a massive opportunity and we need to integrate it." All agents accepted the integration goal and debated HOW, not WHETHER.

Key Consensus (3+ agents agreed)

1. The Compound step is the #1 integration target. Every agent identified institutional knowledge capture as the highest-value technique. Halt has zero mechanism for this today.
2. Compound-engineering should stay as a plugin, supermemory needs local reimplementation. Plugin Architecture showed zero hook conflicts for compound-engineering (it has no hooks). Supermemory collides on 4/4 hook events.
3. The Stop hook race condition is dangerous. Halt's stop-validator.py (exit code 2 blocking) running in parallel with supermemory's 30s summary-hook.cjs creates premature transcript uploads.
4. Sensitive code exfiltration to Supermemory's cloud API is a top risk. Transcript-formatter includes file edits, bash commands, and tool results with only 200-500 char truncation and zero secret filtering.

Adversarial Dialogue Outcome

Contested point: Integration scope -- minimal local-only (~310 lines) vs. full cloud-integrated (5-phase Four Buckets architecture).

First Principles argued: Grep over local YAML gives 80% of semantic search value. The project's own research report warns against "complex memory systems." The LLM itself IS the semantic search engine. No cloud dependency needed.

Context Engineering argued: Most agent failures are context failures. The tiered retrieval protocol (static + semantic + grep + on-demand) ensures right context at right time. Local grep cannot do semantic similarity matching.

Resolution: Context Engineering conceded the architecture but proved the problem. Key evidence:

• 13 commits on auto-approval subsystem, each session discovering one new edge case
• 473 lines of PID-scoping built and destroyed -- no record of why it failed
• 2-entry MEMORIES.md for a 137-commit project

Context Engineering's concession: "I was proposing a cathedral when a well-placed bridge would suffice."

First Principles' concession: "Cross-session knowledge loss is real and measured, not theoretical."

Persistent disagreement: Whether grep degrades past ~200 solution files. First Principles says grep + LLM keyword expansion is sufficient indefinitely. Context Engineering says semantic search will be needed at scale. Deferred to Phase 4 -- measure before optimizing.

Critical Reviewer: Top 10 Risks

Plugin Architecture Analysis

compound-engineering as plugin (recommended):

• Zero hooks -- no composition risk
• One skill name collision (frontend-design) resolved by plugin namespacing (/compound-engineering:frontend-design)
• Zero command collisions (uses workflows: prefix)
• Context7 MCP adds value without conflict
• Installation: /plugin marketplace add + /plugin install compound-engineering

supermemory extracted into halt (alternative considered but rejected):

• Would require copying 6 CJS scripts into config/hooks/supermemory/
• Would require rewriting ${CLAUDE_PLUGIN_ROOT} references
• Would add Node.js runtime dependency alongside Python
• Would require manual upstream update tracking
• Rejected in favor of local-only reimplementation

Context Engineering: Four Buckets Assessment

Appendix: Evidence of Cross-Session Knowledge Loss

Auto-Approval Saga (13 commits)

458bee2 fix(appfix): Add PermissionRequest hook to auto-approve ExitPlanMode
2fa03e1 feat(appfix): Add Bash auto-approval for autonomous execution
b573a9c fix(hooks): Add Edit and Write to PermissionRequest auto-approve
5833db2 feat(hooks): Add PreToolUse auto-approval for post-compaction issues
bd8edc1 fix(hooks): add PermissionRequest hook for auto-approval
df4fb9b fix(hooks): remove permissionDecisionReason from allow decisions
76c01ff refactor(hooks): consolidate auto-approval and add references
749f6c2 fix(hooks): add user-level state check to get_autonomous_state()
83cae39 fix(hooks): preserve user-level state across sessions
672b1f2 fix(hooks): enable cross-directory auto-approval via session_id trust
26aa11d feat(hooks): add multi-session auto-approval support
5a170d8 fix(hooks): correct PermissionRequest hook filename
7f83dec feat(hooks): consolidate autonomous mode to /repair and /forge

Each session discovered ONE edge case. With a solutions knowledge base, session #4 would have known all remaining edge cases from sessions #1-3.

PID-Scoping Build-and-Destroy (473 lines)

8b96cb3 (14:25) feat(hooks): add PID-scoped state files -- 473 lines, "confidence: high"
11bee54 (between) fix(hooks): macOS _get_ancestor_pid() basename fix
6307db7 (14:50) refactor(hooks): remove broken PID-scoping -- 60 files modified

The completion checkpoint reads: "confidence_level": "high", "what_remains": "none" -- for a feature entirely ripped out 25 minutes later. No record exists of WHY it failed, preventing future sessions from learning.