Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/severity1/claude-code-auto-memory

Claude Code plugin that automatically maintains CLAUDE.md files
https://github.com/severity1/claude-code-auto-memory

Last synced: 4 days ago
JSON representation

Claude Code plugin that automatically maintains CLAUDE.md files

Awesome Lists containing this project

README 

          
# claude-code-auto-memory



**Your CLAUDE.md, always in sync.** Minimal tokens. Zero config. Just works.



A Claude Code plugin that watches what Claude Code edits, deletes, and moves - then quietly updates your project memory in the background. No manual maintenance needed.



[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blueviolet)](https://claude.ai/code)

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

[![Zero Config](https://img.shields.io/badge/setup-zero--config-brightgreen)]()

[![Token Efficient](https://img.shields.io/badge/tokens-minimal--overhead-blue)]()



## The Problem



CLAUDE.md files become stale as codebases evolve:



- Build commands change but memory stays outdated

- Architecture shifts go unrecorded

- Code conventions drift without memory updates

- New team members get incorrect context



**Manual maintenance is tedious and often forgotten.**



## The Solution



claude-code-auto-memory automatically updates CLAUDE.md when Claude Code makes changes. Processing happens in an isolated agent, so it doesn't consume your main conversation's context window.



```

Claude Code edits code -> Plugin tracks changes -> Isolated agent updates memory -> Context stays fresh

```



## Features



- **Automatic sync**: Tracks Edit/Write/Bash operations and updates CLAUDE.md at end of turn

- **Bash operation tracking**: Detects rm, mv, git rm, git mv, unlink commands

- **Minimal-token tracking**: PostToolUse hook has no output; stop hook triggers isolated agent

- **Isolated processing**: Agent runs in separate context window, doesn't consume main session tokens

- **Marker-based updates**: Only modifies AUTO-MANAGED sections, preserves manual content

- **Subtree support**: Hierarchical CLAUDE.md for monorepos



## Installation



### From Marketplace



```bash

claude plugin marketplace add severity1/severity1-marketplace

claude plugin install auto-memory@severity1-marketplace

```



### Local Development



```bash

# Add local marketplace

claude plugin marketplace add /path/to/claude-code-auto-memory/.dev-marketplace/.claude-plugin/marketplace.json



# Install from local

claude plugin install auto-memory@local-dev

```



## Commands



### `/auto-memory:init`



Initialize CLAUDE.md structure for your project with an interactive wizard.



```

/auto-memory:init

```



The wizard will:

1. Analyze your codebase structure

2. Detect frameworks and build commands

3. Identify subtree candidates (for monorepos)

4. Present findings for your approval

5. Generate CLAUDE.md with auto-managed sections



### `/auto-memory:calibrate`



Force a full recalibration of all CLAUDE.md files.



```

/auto-memory:calibrate

```



### `/auto-memory:sync`



Sync CLAUDE.md with manual file changes detected by git. Use this when you've edited files outside Claude Code (in your IDE, terminal, etc.) and want to update memory without a full recalibration.



```

/auto-memory:sync

```



Detects:

- Modified tracked files (`git diff`)

- Staged files (`git diff --cached`)

- New untracked files (`git ls-files --others`)



### `/auto-memory:status`



Show current sync status and pending changes.



```

/auto-memory:status

```



## How It Works



```mermaid

sequenceDiagram

    participant User

    participant Claude as Claude Code

    participant PostHook as PostToolUse Hook

    participant DirtyFiles as dirty-files

    participant StopHook as Stop Hook

    participant Agent as memory-updater Agent

    participant Skill as memory-processor Skill



    User->>Claude: Edit files

    Claude->>PostHook: Edit/Write/Bash operation

    PostHook->>DirtyFiles: Append file path (zero tokens)

    Note over PostHook: No output - pure tracking



    User->>Claude: Continue working...

    Claude->>PostHook: More edits

    PostHook->>DirtyFiles: Append paths



    Note over Claude: Turn ends

    Claude->>StopHook: End of turn

    StopHook->>DirtyFiles: Check for dirty files



    alt Dirty files exist

        StopHook->>Agent: Spawn isolated agent

        Agent->>Skill: Invoke memory-processor

        Skill->>Skill: Analyze changes

        Skill->>Skill: Update CLAUDE.md sections

        Agent-->>StopHook: Complete

        StopHook->>DirtyFiles: Clear processed files

    else No dirty files

        Note over StopHook: No action needed

    end

```



### Architecture Overview



```

PostToolUse Hook (Edit|Write|Bash)

    |

    v (append file paths)

.claude/auto-memory/dirty-files

    |

    v (end of turn)

Stop Hook

    |

    v (spawn agent)

memory-updater Agent (isolated context)

    |

    v (invoke skill)

memory-processor Skill

    |

    v

CLAUDE.md updated

```



### Token Efficiency



- **PostToolUse hook**: Zero token cost (no output)

- **Stop hook**: Minimal output only when dirty files exist

- **Agent**: Runs in isolated context window - doesn't consume main session tokens

- **Skills**: Progressive disclosure - load only when invoked



## CLAUDE.md Format



Auto-managed sections use HTML comment markers:



```markdown



Content automatically updated by plugin



Content never touched by plugin



```



### Supported Sections



- `project-description` - Project overview

- `build-commands` - Build, test, lint commands

- `architecture` - Directory structure, components

- `conventions` - Code standards, naming patterns

- `patterns` - AI-detected coding patterns

- `git-insights` - Decisions from commit history

- `best-practices` - From official Claude Code docs



## Configuration



Optional configuration is stored in `.claude/auto-memory/config.json`.



### Trigger Modes



Control when auto-memory triggers CLAUDE.md updates:



```json

{

  "triggerMode": "default"

}

```



| Mode | Behavior |

|------|----------|

| `default` | Track file edits in real-time (Edit/Write/Bash operations). Best for most workflows. |

| `gitmode` | Only trigger on `git commit`. Best for developers who commit frequently. |



**Note**: If no config file exists, `default` mode is used.



### Git Commit Enrichment



When a `git commit` is detected (in both modes), auto-memory captures the commit context:

- Commit hash and message are stored inline with each file path: `/path/to/file [hash: message]`

- The memory-updater agent uses this to provide semantic context: "Changes from commit [hash]: [message]"



This helps CLAUDE.md updates reflect the *intent* behind changes, not just which files changed.



### Data Files



| File | Location | Purpose |

|------|----------|---------|

| `dirty-files` | `.claude/auto-memory/` | List of files pending CLAUDE.md update |

| `config.json` | `.claude/auto-memory/` | Trigger mode configuration |



## Development



### Setup



```bash

# Install dev dependencies

uv sync --extra dev



# Run tests

uv run pytest



# Format code

uv run ruff format .



# Lint

uv run ruff check .



# Type check

uv run mypy .

```



### Project Structure



```

claude-code-auto-memory/

├── .claude-plugin/

│   └── plugin.json           # Plugin metadata

├── hooks/

│   └── hooks.json            # Hook registration

├── scripts/

│   ├── post-tool-use.py      # Track file changes

│   └── stop.py               # End-of-turn trigger

├── agents/

│   └── memory-updater.md     # Orchestrator agent

├── skills/

│   ├── memory-processor/     # Update processing

│   └── codebase-analyzer/    # Init wizard

├── commands/

│   ├── init.md               # /auto-memory:init

│   ├── calibrate.md          # /auto-memory:calibrate

│   ├── sync.md               # /auto-memory:sync

│   └── status.md             # /auto-memory:status

└── tests/

```



## Why claude-code-auto-memory?



| Feature | claude-code-auto-memory | Other Solutions |

|---------|-------------------|-----------------|

| Token overhead | **Minimal** (isolated agent) | Hook output adds tokens |

| External deps | **None** | SQLite, Vector DBs, Workers |

| Processing | **Isolated agent** | Inline or external service |

| Updates | **Marker-based** | Full file regeneration |

| Monorepo | **Subtree CLAUDE.md** | Root only |

| Config required | **Optional** (zero-config default) | Config files needed |



See also: [memory-store-plugin](https://github.com/julep-ai/memory-store-plugin), [claude-mem](https://github.com/thedotmack/claude-mem), [claude-code-branch-memory-manager](https://github.com/Davidcreador/claude-code-branch-memory-manager)



## License



MIT



---



**Keywords**: Claude Code plugin, CLAUDE.md, automatic memory, memory management, context persistence, token-efficient, zero-config, monorepo, AI coding assistant