Unsevered Memory

A markdown-based memory system for Claude Code with enforced persistence.

Changelog

• Added support for Claude plugins + npx packaging

What Makes This Different

Most memory systems inject context at session start and hope Claude remembers. This doesn't work because:

1. Context compaction loses early instructions
2. Claude has no obligation to follow suggestions
3. Long sessions forget the protocol

Unsevered Memory solves this with enforcement:

| Hook | When | Purpose | |------|------|---------| | SessionStart | Session begins | Load full context | | UserPromptSubmit | Every prompt | Inject state reminder | | SessionEnd | Session ends | Archive + remind |

The UserPromptSubmit hook survives context compaction by being injected fresh on every message.

Architecture

Enforcement Layer
├── SessionStart ──────> Load context.md + scratchpad
├── UserPromptSubmit ──> [Memory] Task: X | Scratchpad: Y lines
└── SessionEnd ────────> Archive scratchpad, remind to update

File Structure
├── .claude/memory/     # Dynamic (every session)
│   ├── context.md      # Current state, next steps
│   ├── scratchpad.md   # Live session operations
│   ├── decisions.md    # Architectural choices
│   └── sessions/       # Daily archives
│
└── .ai/                # Static (when patterns emerge)
    ├── core/           # Tech stack, architecture
    ├── patterns/       # Reusable solutions (after 3+ uses)
    └── workflows/      # Dev processes

Installation

Choose your preferred method:

Option A: Claude Plugin (Recommended)

# Add marketplace
/plugin marketplace add blas0/UnseveredMemory

# Install plugin
/plugin install unsevered-memory@blas0

Then per-project:

cd /path/to/your/project
/unsevered-memory project

Option B: npx

# Global setup
npx unsevered-memory init

# Per-project setup
cd /path/to/your/project
npx unsevered-memory project

Option C: Manual

git clone https://github.com/blas0/UnseveredMemory.git
cd UnseveredMemory
./setup-global.sh

Then per-project:

cd /path/to/your/project
~/.claude/setup-project.sh

What Gets Installed

Global (~/.claude/):

• CLAUDE.md - Global memory protocol
• settings.json - Hook configuration (3 hooks)
• hooks/ - memory-load, memory-remind, memory-save
• skills/orchestrate/ - Workflow instructions
• commands/orchestrate.md - Orchestrator command

Per-Project:

project/
├── CLAUDE.md               # Project instructions
├── .ai/                    # Static documentation
│   ├── core/
│   │   ├── technology-stack.md
│   │   └── architecture.md
│   ├── patterns/
│   └── workflows/
└── .claude/
    └── memory/
        ├── context.md      # Cross-session state
        ├── scratchpad.md   # Live session log
        ├── decisions.md    # Decision log
        └── sessions/       # Daily archives

Workflow

Session Start

1. Hook loads context.md and scratchpad.md
2. Claude sees current state and any unfinished work
3. Hook hints about .ai/ documentation

During Session

Every prompt shows:

[Memory] Task: Fix auth bug | Scratchpad: 24 lines | .ai/ updated: 2024-01-15

Claude writes to scratchpad.md as it works:

## Session: 2024-01-15 14:30

### Operations
- [14:35] Found issue in validateToken() at src/auth.ts:142
- [14:40] Fixed: was comparing wrong field

### Decisions
- Keep backward compatibility by checking both fields

Claude updates .ai/ when patterns emerge (3+ uses).

Session End

1. Hook archives scratchpad to sessions/YYYY-MM-DD.md
2. Hook reminds to update context.md
3. Claude updates context with current state

Orchestrator Mode

For complex multi-step tasks:

/orchestrate Implement user authentication with JWT

The orchestrator:

1. Reads all memory files
2. Breaks task into subtasks
3. Delegates to specialized agents
4. Updates memory after each step
5. Never loses context

File Purposes

| File | Content | Update Frequency | |------|---------|------------------| | context.md | Current state, next steps | End of session | | scratchpad.md | Operations, findings | During session | | decisions.md | Architectural choices | When decisions made | | .ai/core/ | Tech stack, architecture | When they change | | .ai/patterns/ | Reusable solutions | After 3+ uses |

Repository Structure

UnseveredMemory/
├── .claude-plugin/           # Plugin manifest
│   ├── plugin.json
│   └── marketplace.json
├── package.json              # npm package
├── bin/cli.js                # npx entry point
├── src/commands/             # CLI commands
├── setup-global.sh           # Manual installer
├── scripts/                  # Hook scripts (plugin)
├── hooks/                    # Hook scripts + hooks.json
├── skills/
│   └── orchestrate/
│       └── SKILL.md
├── commands/
│   └── orchestrate.md
└── templates/
    └── [all templates]

Philosophy

• Enforced - UserPromptSubmit hook survives context compaction
• Simple - Bash + markdown, no databases, no APIs
• Offline - Everything is local files
• Native - Uses Claude Code's built-in hooks system
• Proactive - Claude updates .ai/ during work, not after

Enforcement Levels

| Approach | Reliability | |----------|-------------| | CLAUDE.md only | ~30% | | + SessionStart | ~50% | | + UserPromptSubmit | ~75% | | + /orchestrate orchestrator | ~95% |

Uninstall

# npx
npx unsevered-memory uninstall

# Manual
rm -rf ~/.claude/hooks/memory-*.sh
rm -rf ~/.claude/skills/orchestrate
rm -rf ~/.claude/commands/orchestrate.md

# Project files (optional)
rm -rf .claude/memory
rm -rf .ai