Skip to content

About

Simple, organic, lightweight yet purposeful memory system for Claude Code.

www.npmjs.com/package/unsevered-memory

Topics

ai-codingclaudeclaude-codedeveloper-toolshooksmarkdownmemorypersistenceproductivity

Resources

Readme
MIT license
Activity

Stars

49 stars

Watchers

0 watching

Forks

3 forks
Report repository
BranchesTags

Repository files navigation

Unsevered Memory

Unsevered Memory

Claude Code Bash Markdown npm

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

About

Simple, organic, lightweight yet purposeful memory system for Claude Code.

www.npmjs.com/package/unsevered-memory

Topics

ai-codingclaudeclaude-codedeveloper-toolshooksmarkdownmemorypersistenceproductivity

Resources

Readme
MIT license
Activity

Stars

49 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

Packages

Contributors

Languages