Skip to content
Back to search

automem-plus

MarketplaceWorks with Claude CodeGitHub

automem-plus: a thin layer on Claude Code's built-in auto memory

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/6e6p1k--automem-plus/badge.svg)](/listings/6e6p1k--automem-plus)

HTML

<a href="/listings/6e6p1k--automem-plus"><img src="/api/listings/6e6p1k--automem-plus/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

claude plugin marketplace add 6e6p1k/automem-plus
claude plugin install automem-plus@automem-plus

Restart Claude Code. To try it for one session without installing, clone the repo and run `claude --plugin-dir /path/to/automem-plus`.

Then, in any project, type:

/automem-plus:status

It shows whether the rules were injected, whether a handoff exists, and whether this project syncs. `/automem-plus:help` lists every command, and typing `/automem` brings them up in the menu.

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.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "automem-plus",
  3. "description": "automem-plus: a thin layer on Claude Code's built-in auto memory",
  4. "owner": {
  5. "name": "6e6p1k"
  6. },
  7. "plugins": [
  8. {
  9. "name": "automem-plus",
  10. "source": "./",
  11. "description": "Handoff notes, facts mentioned in passing, sync between machines and a usage review, on top of built-in auto memory"
  12. }
  13. ]
  14. }
README.md · README · 217 lines
  1. # automem-plus
  2. A thin layer on [Claude Code](https://claude.com/claude-code)'s built-in auto memory.
  3. Built-in auto memory stores notes per project and loads them into each session. automem-plus doesn't replace it and keeps no notes of its own. It adds what built-in memory doesn't do: it keeps a handoff note current so the next session can continue, saves facts you mention in passing, carries notes between your machines through a git repo you own, and measures which of its own features are worth keeping.
  4. It's three hooks and a dozen slash commands. It makes no model calls of its own unless you run the canary, and the notes stay ordinary auto-memory files that Claude Code reads without the plugin.
  5. > **Status:** early (0.7). Written and used by one person, covered by tests, and tried in real sessions on macOS. Sync has not yet been run between two real machines over a long period. See [Limits](#limits).
  6. ## What it adds
  7. | Built-in auto memory alone | With automem-plus |
  8. |---|---|
  9. | A "where we are" note gets written sometimes and then goes stale | **Handoff note:** one note per branch with Goal, Where we are, Tried and failed, Open decisions, Next steps. Claude rewrites it when you say you're done, after a push, or on `/automem-plus:handoff` |
  10. | Facts mentioned while asking for something else aren't saved | **Passing facts:** "our CI only runs on Fridays" gets saved like an explicit "remember this" |
  11. | Notes live on one machine, under one clone path | **Sync:** notes travel through a private git repo, matched by the project's origin URL. Preferences you promote to user-level rules travel too |
  12. | Two machines can leave the same fact under two names, or notes that disagree | **Reconcile:** `/automem-plus:reconcile` has Claude unite them. It proposes, you agree, it edits |
  13. | Nothing tells you a status note is out of date | **Nudge:** a line after a turn when you committed and the handoff is older than the commit |
  14. | No way to tell which memory habits pay off | **Review:** a local usage log, and a keep-or-retire suggestion per feature |
  15. The first two rows describe built-in behaviour on Claude Code 2.1.323, checked with the plugin's own [canary](#review-and-the-canary). Built-in memory keeps improving, which is why every feature here can be measured and switched off.
  16. ## Requirements
  17. - Claude Code with auto memory on (the plugin does nothing in projects where it's off).
  18. - `python3` 3.9 or newer on your PATH. No packages to install.
  19. - `git`, for sync and the commit nudge. The rules work without it.
  20. - macOS or Linux, including WSL. Native Windows is untested.
  21. ## Install
  22. ```bash
  23. claude plugin marketplace add 6e6p1k/automem-plus
  24. ```
  25. ```bash
  26. claude plugin install automem-plus@automem-plus
  27. ```
  28. Restart Claude Code. To try it for one session without installing, clone the repo and run `claude --plugin-dir /path/to/automem-plus`.
  29. Then, in any project, type:
  30. ```text
  31. /automem-plus:status
  32. ```
  33. It shows whether the rules were injected, whether a handoff exists, and whether this project syncs. `/automem-plus:help` lists every command, and typing `/automem` brings them up in the menu.
  34. ## How it works
  35. | Hook | What it does | Cost |
  36. |---|---|---|
  37. | Session start | Adds the two rules to Claude's context. In a git repo that syncs, it also pulls and merges notes and promoted rules from the store (bounded to a few seconds) | The rules' text, about 550 tokens |
  38. | Your prompt | Sees the plugin's commands before Claude does. It answers most of them itself and blocks the prompt; `handoff` and `reconcile` pass through to Claude with extra instructions | None for the answered ones: no model turn, and nothing added to Claude's context |
  39. | End of each turn | Reads the transcript for which notes were read or written, shows a notice if one applies, and pushes notes in the background if any changed | None |
  40. The notices after a turn are one line each, shown to you and not to Claude:
  41. - you committed and the handoff note is older than the commit;
  42. - a sync found notes that differ between machines, so `/automem-plus:reconcile` has something to do;
  43. - Claude Code was updated, so the canary may be worth running;
  44. - a month of usage is logged, so a review is due.
  45. The plugin never writes or edits a note. Claude does, following the rules, into the same folder built-in memory uses. Sync copies whole files and never looks inside them.
  46. ## The handoff note
  47. The rule tells Claude to keep one note for the work in this session: `handoff-<branch>.md` in a git repo (worktrees share one memory folder, so each branch gets its own), plain `handoff.md` elsewhere.
  48. - **Updated** when you say you're done for now, after a push, and on `/automem-plus:handoff`. It's rewritten in place.
  49. - **Read** at the start of a session when your first message is about continuing, and checked against `git log`.
  50. - **Folded:** an older status note about the same work is merged into it and removed. Handoffs of branches that no longer exist are pointed out at session start.
  51. Nothing forces Claude to do this. It's an instruction, backed by the nudge and measured by the review. The rule texts are in [`rules/`](rules/).
  52. ## Sync between machines
  53. Sync is off until you create the store, a git repo at `~/.claude/memory-store/`.
  54. 1. Create a **private** repo on your git host, then: `/automem-plus:store <git-url>`. Without a remote, `/automem-plus:store init` makes a local store.
  55. 2. Say whose repos sync: `/automem-plus:owner <your-github-name>`. Projects whose origin belongs to that account then sync automatically.
  56. 3. For any other project: `/automem-plus:sync on` opts it in, `/automem-plus:sync off` keeps it local-only.
  57. On a second machine, install the plugin and run step 1 with the same URL. The owner list comes with the store.
  58. **How the merge works.** It's a three-way merge per note, against what was last synced:
  59. - **Changed on one side:** that side wins, and deletions propagate.
  60. - **Changed on both sides:** the local copy wins and the other is saved.
  61. - **First seen on both sides:** the newer copy wins and the other is saved.
  62. - **`MEMORY.md`:** merged line by line. Lines either side removed stay removed, and new lines from both are kept.
  63. **Promoted rules travel too.** `/automem-plus:promote` moves a preference out of one project's memory into `~/.claude/rules/automem-<note>.md`, which every project loads. The note's deletion syncs, so the rule does as well: every sync of any project also merges the `automem-*.md` files at the top of `~/.claude/rules/` with the store's `automem/_rules/` folder, which belongs to no repo. The merge is the one notes get: a rule changed on one side wins, a rule both machines changed keeps the local copy and saves the other, and deleting a rule on one machine deletes it on the others after a backup. Rules without the `automem-` prefix are yours and are never read, written or deleted.
  64. **What keeps it safe:**
  65. - Before a note or a promoted rule is overwritten or deleted by an import, the local copy is saved under the state folder's `backups/`.
  66. - There is no `git reset` anywhere. A rejected push is merged, never forced.
  67. - An emptied memory folder or a re-created store is never read as "delete everything". The rules folder is the exception for emptying: deleting your last promoted rule is a deletion like any other.
  68. - A note or promoted rule that looks like it holds a credential is never pushed, and neither is its index line. This is pattern matching, so treat it as a safety net, not a guarantee.
  69. - Sync turns itself off when `autoMemoryDirectory` is set at user or project level, because then the folder isn't one repo's alone.
  70. ## Uniting memory from two machines
  71. A file merge can't see that two notes say the same thing, or that they disagree. After two machines' notes have been brought together, run this on the machine that joined second:
  72. ```text
  73. /automem-plus:reconcile
  74. ```
  75. Claude gets the copies that lost a file conflict (quoted, up to 20 copies of 6,000 characters each), the names of the notes that arrived from the other machine, and these rules:
  76. - **The same thing in two notes:** merge into one.
  77. - **A copy that lost a conflict:** carry over anything true that the kept note lacks.
  78. - **Notes that disagree:** the newer one doesn't win by default. The state of the work is checked against `git log` and goes into the handoff. A preference of yours is shown both ways and you're asked. A fact is checked or asked about.
  79. It lists every change with a reason first and changes nothing until you answer. The result syncs like any other edit, and earlier versions stay in the store's git history.
  80. Run it where the two copies met: the copy that lost is saved only on that machine.
  81. ## Review and the canary
  82. Each feature in [`features.json`](features.json) declares up front what "used" means and when it should be retired.
  83. - **`/automem-plus:review`** reads the local usage log and gives each feature a verdict: collecting data, keep, or retire. You decide with `/automem-plus:retire <feature>` and `/automem-plus:enable <feature>`.
  84. - **`/automem-plus:canary`** checks whether built-in memory now does a feature without the plugin. It makes six short Haiku calls in throwaway repos (about $0.07) with the plugin switched off, and deletes those repos and their memory afterwards. It runs only when you ask.
  85. ## Commands
  86. | Command | What it does | Answered by |
  87. |---|---|---|
  88. | `/automem-plus:handoff` | Claude updates the handoff note now | Claude |
  89. | `/automem-plus:status` | Is it working here: rules, handoff, sync, promoted rules, anything waiting | the hook |
  90. | `/automem-plus:review` | Which features and notes earn their keep | the hook |
  91. | `/automem-plus:reconcile [all]` | Claude unites memory merged from several machines. `all` repeats copies from earlier runs | Claude |
  92. | `/automem-plus:sync [on\|off]` | This repo's sync. `on` opts it in, `off` keeps it local-only | the hook |
  93. | `/automem-plus:store <git-url>\|init` | Clone your store repo. `init` makes a local one | the hook |
  94. | `/automem-plus:owner <github-name>` | Repos owned by this account sync automatically | the hook |
  95. | `/automem-plus:promote [<note>]` | List preference notes, or move one into `~/.claude/rules/` so every project gets it, on every machine that syncs | the hook |
  96. | `/automem-plus:retire <feature>` | Turn a feature off | the hook |
  97. | `/automem-plus:enable <feature>` | Turn a feature back on | the hook |
  98. | `/automem-plus:canary` | Check whether built-in memory now covers these features | the hook |
  99. | `/automem-plus:help` | This list | the hook |
  100. **Why two kinds.** A plugin's slash command is normally a prompt handed to Claude, which costs a model turn. For everything that is only a lookup or a setting, the prompt hook answers first and blocks the prompt, so the command costs no tokens and leaves nothing in Claude's context. The commands still exist as skills, which is what puts them in the `/` menu.
  101. **Short form.** Every command also works as `::automem <name>`, and the handoff as `::handoff`. The hook treats both spellings the same.
  102. Answers from the hook are plain text, because Claude Code shows them without rendering markdown. Claude Code frames them as a prompt "blocked by hook"; that wording is its own, not an error.
  103. ## Configuration
  104. | Setting | Default | What it is |
  105. |---|---|---|
  106. | `AUTOMEM_DISABLE` | unset | Any non-empty value switches every hook off for that process |
  107. | `AUTOMEM_STORE` | `~/.claude/memory-store` | The store repo |
  108. | `AUTOMEM_STATE` | `~/.claude/memory-state/automem` | Machine-local state: usage log, sync bases, backups |
  109. | `features.json` | all on | The features and their retire rules. The `retire` and `enable` commands keep your choice in the state folder |
  110. Thresholds such as "a working session is three or more prompts" are named in [`scripts/automem/constants.py`](scripts/automem/constants.py).
  111. ## Privacy and security
  112. - **Nothing is sent anywhere except your own store.** Notes go to the git remote you configured, and only for projects you opted in. Promoted rules (`~/.claude/rules/automem-*.md`) go there too whenever any project syncs; the rest of `~/.claude/rules/` is never read. There is no telemetry.
  113. - **The usage log holds no note content.** It records timestamps, event names, note file names (a handoff's name includes the branch), a hash of the repo's origin, and the type of an error when a sync fails. It stays on the machine.
  114. - **The transcript is read locally,** only to find tool calls that touched the memory folder.
  115. - **Hooks run as you.** Like any Claude Code plugin with hooks, this one runs Python on your machine with your permissions on every session. The code is about 2,500 lines in [`scripts/`](scripts/); read it before installing.
  116. - **Keep the store private.** Your notes can hold anything you've told Claude about a project.
  117. ## Limits
  118. - **Cloud sessions:** Claude Code's cloud and mobile sessions don't load plugins installed on your machine, so the plugin doesn't run there.
  119. - **Not yet proven over time:** two-machine sync and reconcile are covered by tests with two simulated machines and by one real trial each, not by months of use. Long sessions with compaction are untested.
  120. - **Usage counting reads command text.** A note counts as read or written when a tool call names it: by full path, by a variable set in the same command, by a glob, or by a bare name after `cd` into the memory folder. A variable set in an earlier command, and edits made by a script inside a heredoc, aren't counted.
  121. - **Facts used straight from their index line aren't counted,** because the note is never opened. The passing-facts rule therefore has no automatic verdict; the canary judges it.
  122. - **The memory folder's name is inferred.** Claude Code doesn't document how it names project folders, so sync writes only into a folder that already exists or that the session's own transcript path confirms.
  123. - **Deleting every note doesn't propagate.** It's indistinguishable from a wiped folder, so the notes come back. Delete them one at a time. This includes promoting the only note a project has: it comes back on the next sync, next to its new rule.
  124. - **Promoted rules move only with a project's sync.** A machine picks them up at the first session in a project that syncs.
  125. - **Index lines arriving at session start:** Claude Code loads `MEMORY.md` before hooks run, so lines that just arrived are passed to Claude in the session context instead.
  126. ## Troubleshooting
  127. - **Nothing happens.** Run `/automem-plus:status`. If auto memory is off for the project, the plugin stays out of the way by design.
  128. - **A hook error mentions `python3`.** It isn't on the PATH Claude Code sees.
  129. - **Status says a push failed.** The commit is safe in the local store; the next sync retries. Check that `git push` works in `~/.claude/memory-store`.
  130. - **You want it off for one command or script.** Set `AUTOMEM_DISABLE=1`. To turn it off everywhere, `claude plugin disable automem-plus@automem-plus`.
  131. - **A note was overwritten and you want the old one.** Look in `~/.claude/memory-state/automem/backups/`, or in the store's git history.
  132. ## Development
  133. ```text
  134. hooks/hooks.json the three hooks
  135. skills/ one per command, so each shows in the / menu
  136. rules/ the texts Claude is given
  137. features.json each feature's "used" measure and retire rule
  138. scripts/*.py hook entry points and two background jobs
  139. scripts/automem/ the package, one module per concern
  140. tests/ pytest, split by subject
  141. ```
  142. Tests need only pytest and git. They run in temp dirs and never touch your real `~/.claude`, store or memory:
  143. ```bash
  144. python3 -m pytest -q
  145. ```
  146. ```bash
  147. ruff check . && ruff format --check .
  148. ```
  149. Sync's merge rules are documented at the top of [`scripts/automem/merge.py`](scripts/automem/merge.py).
  150. ## License
  151. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

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