Skip to content
Back to search

claude-code-auto-memory

Claude Code plugin that automatically maintains CLAUDE.md files

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/severity1--claude-code-auto-memory/badge.svg)](/listings/severity1--claude-code-auto-memory)

HTML

<a href="/listings/severity1--claude-code-auto-memory"><img src="/api/listings/severity1--claude-code-auto-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

From Marketplace

claude plugin marketplace add severity1/severity1-marketplace
claude plugin install auto-memory@severity1-marketplace

Local Development

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 294 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # claude-code-auto-memory
  2. **Your CLAUDE.md, always in sync.** Minimal tokens. Zero config. Just works.
  3. 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.
  4. [![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blueviolet)](https://claude.ai/code)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  6. [![Zero Config](https://img.shields.io/badge/setup-zero--config-brightgreen)]()
  7. [![Token Efficient](https://img.shields.io/badge/tokens-minimal--overhead-blue)]()
  8. ## The Problem
  9. CLAUDE.md files become stale as codebases evolve:
  10. - Build commands change but memory stays outdated
  11. - Architecture shifts go unrecorded
  12. - Code conventions drift without memory updates
  13. - New team members get incorrect context
  14. **Manual maintenance is tedious and often forgotten.**
  15. ## The Solution
  16. 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.
  17. ```
  18. Claude Code edits code -> Plugin tracks changes -> Isolated agent updates memory -> Context stays fresh
  19. ```
  20. ## Features
  21. - **Automatic sync**: Tracks Edit/Write/Bash operations and updates CLAUDE.md at end of turn
  22. - **Bash operation tracking**: Detects rm, mv, git rm, git mv, unlink commands
  23. - **Minimal-token tracking**: PostToolUse hook has no output; stop hook triggers isolated agent
  24. - **Isolated processing**: Agent runs in separate context window, doesn't consume main session tokens
  25. - **Marker-based updates**: Only modifies AUTO-MANAGED sections, preserves manual content
  26. - **Subtree support**: Hierarchical CLAUDE.md for monorepos
  27. ## Installation
  28. ### From Marketplace
  29. ```bash
  30. claude plugin marketplace add severity1/severity1-marketplace
  31. claude plugin install auto-memory@severity1-marketplace
  32. ```
  33. ### Local Development
  34. ```bash
  35. # Add local marketplace
  36. claude plugin marketplace add /path/to/claude-code-auto-memory/.dev-marketplace/.claude-plugin/marketplace.json
  37. # Install from local
  38. claude plugin install auto-memory@local-dev
  39. ```
  40. ## Commands
  41. ### `/auto-memory:init`
  42. Initialize CLAUDE.md structure for your project with an interactive wizard.
  43. ```
  44. /auto-memory:init
  45. ```
  46. The wizard will:
  47. 1. Analyze your codebase structure
  48. 2. Detect frameworks and build commands
  49. 3. Identify subtree candidates (for monorepos)
  50. 4. Present findings for your approval
  51. 5. Generate CLAUDE.md with auto-managed sections
  52. ### `/auto-memory:calibrate`
  53. Force a full recalibration of all CLAUDE.md files.
  54. ```
  55. /auto-memory:calibrate
  56. ```
  57. ### `/auto-memory:sync`
  58. 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.
  59. ```
  60. /auto-memory:sync
  61. ```
  62. Detects:
  63. - Modified tracked files (`git diff`)
  64. - Staged files (`git diff --cached`)
  65. - New untracked files (`git ls-files --others`)
  66. ### `/auto-memory:status`
  67. Show current sync status and pending changes.
  68. ```
  69. /auto-memory:status
  70. ```
  71. ## How It Works
  72. ```mermaid
  73. sequenceDiagram
  74. participant User
  75. participant Claude as Claude Code
  76. participant PostHook as PostToolUse Hook
  77. participant DirtyFiles as dirty-files
  78. participant StopHook as Stop Hook
  79. participant Agent as memory-updater Agent
  80. participant Skill as memory-processor Skill
  81. User->>Claude: Edit files
  82. Claude->>PostHook: Edit/Write/Bash operation
  83. PostHook->>DirtyFiles: Append file path (zero tokens)
  84. Note over PostHook: No output - pure tracking
  85. User->>Claude: Continue working...
  86. Claude->>PostHook: More edits
  87. PostHook->>DirtyFiles: Append paths
  88. Note over Claude: Turn ends
  89. Claude->>StopHook: End of turn
  90. StopHook->>DirtyFiles: Check for dirty files
  91. alt Dirty files exist
  92. StopHook->>Agent: Spawn isolated agent
  93. Agent->>Skill: Invoke memory-processor
  94. Skill->>Skill: Analyze changes
  95. Skill->>Skill: Update CLAUDE.md sections
  96. Agent-->>StopHook: Complete
  97. StopHook->>DirtyFiles: Clear processed files
  98. else No dirty files
  99. Note over StopHook: No action needed
  100. end
  101. ```
  102. ### Architecture Overview
  103. ```
  104. PostToolUse Hook (Edit|Write|Bash)
  105. |
  106. v (append file paths)
  107. .claude/auto-memory/dirty-files
  108. |
  109. v (end of turn)
  110. Stop Hook
  111. |
  112. v (spawn agent)
  113. memory-updater Agent (isolated context)
  114. |
  115. v (invoke skill)
  116. memory-processor Skill
  117. |
  118. v
  119. CLAUDE.md updated
  120. ```
  121. ### Token Efficiency
  122. - **PostToolUse hook**: Zero token cost (no output)
  123. - **Stop hook**: Minimal output only when dirty files exist
  124. - **Agent**: Runs in isolated context window - doesn't consume main session tokens
  125. - **Skills**: Progressive disclosure - load only when invoked
  126. ## CLAUDE.md Format
  127. Auto-managed sections use HTML comment markers:
  128. ```markdown
  129. <!-- AUTO-MANAGED: section-name -->
  130. Content automatically updated by plugin
  131. <!-- END AUTO-MANAGED -->
  132. <!-- MANUAL -->
  133. Content never touched by plugin
  134. <!-- END MANUAL -->
  135. ```
  136. ### Supported Sections
  137. - `project-description` - Project overview
  138. - `build-commands` - Build, test, lint commands
  139. - `architecture` - Directory structure, components
  140. - `conventions` - Code standards, naming patterns
  141. - `patterns` - AI-detected coding patterns
  142. - `git-insights` - Decisions from commit history
  143. - `best-practices` - From official Claude Code docs
  144. ## Configuration
  145. Optional configuration is stored in `.claude/auto-memory/config.json`.
  146. ### Trigger Modes
  147. Control when auto-memory triggers CLAUDE.md updates:
  148. ```json
  149. {
  150. "triggerMode": "default"
  151. }
  152. ```
  153. | Mode | Behavior |
  154. |------|----------|
  155. | `default` | Track file edits in real-time (Edit/Write/Bash operations). Best for most workflows. |
  156. | `gitmode` | Only trigger on `git commit`. Best for developers who commit frequently. |
  157. **Note**: If no config file exists, `default` mode is used.
  158. ### Git Commit Enrichment
  159. When a `git commit` is detected (in both modes), auto-memory captures the commit context:
  160. - Commit hash and message are stored inline with each file path: `/path/to/file [hash: message]`
  161. - The memory-updater agent uses this to provide semantic context: "Changes from commit [hash]: [message]"
  162. This helps CLAUDE.md updates reflect the *intent* behind changes, not just which files changed.
  163. ### Data Files
  164. | File | Location | Purpose |
  165. |------|----------|---------|
  166. | `dirty-files` | `.claude/auto-memory/` | List of files pending CLAUDE.md update |
  167. | `config.json` | `.claude/auto-memory/` | Trigger mode configuration |
  168. ## Development
  169. ### Setup
  170. ```bash
  171. # Install dev dependencies
  172. uv sync --extra dev
  173. # Run tests
  174. uv run pytest
  175. # Format code
  176. uv run ruff format .
  177. # Lint
  178. uv run ruff check .
  179. # Type check
  180. uv run mypy .
  181. ```
  182. ### Project Structure
  183. ```
  184. claude-code-auto-memory/
  185. ├── .claude-plugin/
  186. │ └── plugin.json # Plugin metadata
  187. ├── hooks/
  188. │ └── hooks.json # Hook registration
  189. ├── scripts/
  190. │ ├── post-tool-use.py # Track file changes
  191. │ └── stop.py # End-of-turn trigger
  192. ├── agents/
  193. │ └── memory-updater.md # Orchestrator agent
  194. ├── skills/
  195. │ ├── memory-processor/ # Update processing
  196. │ └── codebase-analyzer/ # Init wizard
  197. ├── commands/
  198. │ ├── init.md # /auto-memory:init
  199. │ ├── calibrate.md # /auto-memory:calibrate
  200. │ ├── sync.md # /auto-memory:sync
  201. │ └── status.md # /auto-memory:status
  202. └── tests/
  203. ```
  204. ## Why claude-code-auto-memory?
  205. | Feature | claude-code-auto-memory | Other Solutions |
  206. |---------|-------------------|-----------------|
  207. | Token overhead | **Minimal** (isolated agent) | Hook output adds tokens |
  208. | External deps | **None** | SQLite, Vector DBs, Workers |
  209. | Processing | **Isolated agent** | Inline or external service |
  210. | Updates | **Marker-based** | Full file regeneration |
  211. | Monorepo | **Subtree CLAUDE.md** | Root only |
  212. | Config required | **Optional** (zero-config default) | Config files needed |
  213. 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)
  214. ## License
  215. MIT
  216. ---
  217. **Keywords**: Claude Code plugin, CLAUDE.md, automatic memory, memory management, context persistence, token-efficient, zero-config, monorepo, AI coding assistant

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.