Claude Memory: Advanced Claude Code Plugin - Fork Tournaments, Persistent Memory, Output Airlock, Evidence Packs, MCP Data Firewall

gistfile0.txt

# Claude Memory Plugin

A Bun/TypeScript implementation of 5 powerful but rarely-used Claude Code capabilities.

## Features Built

### 1. Fork Tournament (`src/fork-tournament/`)
Parallel exploration with auto-dossiers and winner selection.

**Files:**
- `hooks/session-start.ts` - Surfaces fork dossiers on session resume
- `hooks/session-end.ts` - Writes dossiers + patches on exit
- `tools/score.ts` - LOC, test pass rate, complexity metrics scoring
- `tools/judge.ts` - LLM-as-judge pattern for winner selection
- `tools/merge-lab.ts` - Merge conflict simulation with conflict bundles
- `types.ts` - TypeScript interfaces

**Usage:**
```bash
# Fork your session
claude --continue --fork-session

# Score all forks
bun run tournament:score

# Run the LLM judge
bun run tournament:judge --goal "Fix flaky auth tests"

# Simulate merges
bun run tournament:merge --winner <SESSION_ID>
```

---

### 2. Memory Bank (`src/memory-bank/`)
Persistent preference learning with semantic search.

**Files:**
- `server.ts` - FastMCP server with SQLite + TF-IDF semantic search
- `hooks/session-end-extractor.ts` - Extracts @pref, @alias, @rewrite, @rule, @env tags
- `hooks/pre-tool-use-autocorrect.ts` - Auto-rewrites Bash commands based on learned preferences
- `types.ts` - TypeScript interfaces

**DSL Tags:**
```
@pref package_manager=bun          # Store preferences
@alias "npm test" -> "bun test"    # Command aliases
@rewrite {"type":"prefix","from":"npm","to":"bun"}  # Rewrite rules
@rule never edit migrations        # General rules
@env use python -m pytest          # Environment hints
```

**Conflict Resolution:**
- Latest explicit preference wins
- Low-confidence implicit extractions become "candidate" (won't auto-supersede)
- Pinned memories resist auto-supersede

---

### 3. Noisy Command Airlock (`src/airlock/`)
Token budget governor for verbose outputs.

**Files:**
- `mcp-server.ts` - MCP tool that stores full output to disk, returns compact metadata
- `hooks/post-tool-use-summarizer.ts` - Replaces large outputs with failure-aware summaries
- `hooks/pre-tool-use-redirect.ts` - Redirects noisy commands to the MCP tool
- `types.ts` - TypeScript interfaces

**Features:**
- Full output stored to disk
- Only compact summary in context
- Failure detection (FAIL, Traceback, panic, ERROR, npm ERR!)
- Redirects known-noisy commands (npm test, pytest, cargo test, etc.)

---

### 4. Evidence Pack Factory (`src/evidence-pack/`)
Automatic research artifacts from subagents.

**Files:**
- `hooks/pre-tool-use-tagger.ts` - Injects EVIDENCE_PACK markers into subagent prompts
- `hooks/subagent-stop-writer.ts` - Extracts findings, files, breadcrumbs from transcripts
- `lib/utils.ts` - Helper functions
- `types.ts` - TypeScript interfaces

**Evidence Pack Contents:**
- Files examined (from Read tool uses)
- Key findings (claim + evidence + confidence + caveats)
- Breadcrumbs ([FILE], [PATTERN], [QUESTION], [TODO])

**Output:** `.claude/evidence/<id>.md` with INDEX.md for CLAUDE.local.md imports

---

### 5. MCP Data Firewall (`src/data-firewall/`)
Safe connections to risky MCP servers (DB queries, monitoring, issue trackers).

**Files:**
- `hooks/pre-tool-use-limiter.ts` - Clamps pagination/limit params on MCP tools
- `hooks/post-tool-use-redactor.ts` - Saves raw output to disk, returns redacted summaries
- `config.ts` - Configuration for limit caps and tool-specific overrides
- `types.ts` - TypeScript interfaces

**Default Limits:**
- `limit`: 200
- `max_results`: 50
- `page_size`: 50
- `top_k`: 25
- `first`: 50

**Tool-Specific Overrides:**
- Postgres: stricter (limit=100, max_results=25)
- GitHub: more lenient (per_page=100)

---

## Installation

```bash
git clone <repo>
cd claude-memory
bun install
```

## Configuration

Add to `.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|resume",
      "hooks": [{
        "type": "command",
        "command": "bun run \"$CLAUDE_PROJECT_DIR/src/fork-tournament/hooks/session-start.ts\""
      }]
    }],
    "SessionEnd": [{
      "matcher": "*",
      "hooks": [
        {"type": "command", "command": "bun run \"$CLAUDE_PROJECT_DIR/src/fork-tournament/hooks/session-end.ts\""},
        {"type": "command", "command": "bun run \"$CLAUDE_PROJECT_DIR/src/memory-bank/hooks/session-end-extractor.ts\""}
      ]
    }],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {"type": "command", "command": "bun run \"$CLAUDE_PROJECT_DIR/src/memory-bank/hooks/pre-tool-use-autocorrect.ts\""},
          {"type": "command", "command": "bun run \"$CLAUDE_PROJECT_DIR/src/airlock/hooks/pre-tool-use-redirect.ts\""}
        ]
      },
      {
        "matcher": "Task",
        "hooks": [{"type": "command", "command": "bun run \"$CLAUDE_PROJECT_DIR/src/evidence-pack/hooks/pre-tool-use-tagger.ts\""}]
      },
      {
        "matcher": "mcp__.*",
        "hooks": [{"type": "command", "command": "bun run \"$CLAUDE_PROJECT_DIR/src/data-firewall/hooks/pre-tool-use-limiter.ts\""}]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "mcp__cc_shell__run",
        "hooks": [{"type": "command", "command": "bun run \"$CLAUDE_PROJECT_DIR/src/airlock/hooks/post-tool-use-summarizer.ts\""}]
      },
      {
        "matcher": "mcp__.*",
        "hooks": [{"type": "command", "command": "bun run \"$CLAUDE_PROJECT_DIR/src/data-firewall/hooks/post-tool-use-redactor.ts\""}]
      }
    ],
    "SubagentStop": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "bun run \"$CLAUDE_PROJECT_DIR/src/evidence-pack/hooks/subagent-stop-writer.ts\""}]
    }]
  }
}
```

Add to `CLAUDE.local.md`:
```md
# Local session artifacts
@.claude/forks/INDEX.md
@.claude/evidence/INDEX.md
```

## MCP Servers

```bash
# Memory Bank Server
claude mcp add memory-bank -- bun run src/memory-bank/server.ts

# Airlock Shell Server
claude mcp add cc_shell -- bun run src/airlock/mcp-server.ts
```

## Tests

309 isolated smoke tests across all 5 modules:

| Module | Tests | File |
|--------|-------|------|
| Fork Tournament | 33 | `tests/fork-tournament.test.ts` |
| Memory Bank | 109 | `tests/memory-bank.test.ts` |
| Airlock | 68 | `tests/airlock.test.ts` |
| Evidence Pack | 52 | `tests/evidence-pack.test.ts` |
| Data Firewall | 47 | `tests/data-firewall.test.ts` |

Run all tests:
```bash
bun test
```

Tests use Claude Code's isolation flags:
```bash
claude --setting-sources "" \
       --settings '{"disableAllHooks": true}' \
       --tools "" \
       --no-chrome \
       --disable-slash-commands \
       --model "haiku" \
       --print "..."
```

## Project Structure

```
claude-memory/
├── package.json
├── README.md
├── src/
│   ├── index.ts                    # Main exports + generateCompleteHookConfig()
│   ├── fork-tournament/
│   │   ├── types.ts
│   │   ├── hooks/session-start.ts
│   │   ├── hooks/session-end.ts
│   │   ├── tools/score.ts
│   │   ├── tools/judge.ts
│   │   ├── tools/merge-lab.ts
│   │   └── index.ts
│   ├── memory-bank/
│   │   ├── types.ts
│   │   ├── server.ts
│   │   ├── hooks/session-end-extractor.ts
│   │   ├── hooks/pre-tool-use-autocorrect.ts
│   │   └── index.ts
│   ├── airlock/
│   │   ├── types.ts
│   │   ├── mcp-server.ts
│   │   ├── hooks/post-tool-use-summarizer.ts
│   │   ├── hooks/pre-tool-use-redirect.ts
│   │   └── index.ts
│   ├── evidence-pack/
│   │   ├── types.ts
│   │   ├── hooks/pre-tool-use-tagger.ts
│   │   ├── hooks/subagent-stop-writer.ts
│   │   ├── lib/utils.ts
│   │   └── index.ts
│   └── data-firewall/
│       ├── types.ts
│       ├── config.ts
│       ├── hooks/pre-tool-use-limiter.ts
│       ├── hooks/post-tool-use-redactor.ts
│       └── index.ts
└── tests/
    ├── fork-tournament.test.ts
    ├── memory-bank.test.ts
    ├── airlock.test.ts
    ├── evidence-pack.test.ts
    └── data-firewall.test.ts
```

## License

MIT