auto-memory

Automatically maintains CLAUDE.md files as codebases evolve using hooks, agents, and skills
Open source Open in the app JSON README (API)
About

Automatically maintains CLAUDE.md files as codebases evolve using hooks, agents, and skills
Details

Kind: Plugins
Topic: AI, RAG & memory
Publisher: severity1
Origin: marketplace
Category: ferramentas
Stars: 158
Forks: 16
Open pull requests: 2
Last push: 2026-04-18T03:09:56Z
Repository state: ativo
Language: Python
License: MIT
Added: 2026-08-30 01:48:58
Updated: 2026-08-30 01:48:58
Origin id: severity1/claude-code-auto-memory/auto-memory
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
<!-- AUTO-MANAGED: section-name -->
Content automatically updated by plugin
<!-- END AUTO-MANAGED -->

<!-- MANUAL -->
Content never touched by plugin
<!-- END MANUAL -->
```

### 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