Continuous Memory for Claude Code

Claude Code starts every session blank. It doesn't know what you worked on yesterday, what conventions your team follows, or what mistakes it already made. You re-explain everything, every time.

Claude Remember fixes that. It hooks into Claude Code's lifecycle — saving sessions automatically, compressing them through Haiku into layered daily summaries, and loading them back into context on the next session start. No manual prompting, no copy-pasting notes. The agent starts every session with its history already present.

The result: your Claude Code instance develops continuity. It remembers what it learned, what broke, what worked. Not perfect recall — compressed, practical memory that fits in minimal tokens.

Install

From our marketplace (recommended)

We maintain our own plugin marketplace so updates actually work. Add it once, then install:

/plugin marketplace add Digital-Process-Tools/claude-marketplace
/plugin install remember@dpt-plugins

To update later:

/plugin marketplace update

Restart Claude Code after installing or enabling. Claude Code reads hook registrations when a session starts, so a plugin enabled part-way through one has no hooks wired for the rest of it — PostToolUse never fires and nothing is captured, with no error anywhere (#200). Nothing inside a hook can detect this while it is happening, so the plugin reports it at the next session start instead. If capture seems to be doing nothing, run /remember:doctor.

From the Anthropic Marketplace

Claude Remember is also available in the official Anthropic Marketplace. In Claude Code, type /plugin and search for "remember".

Releases reach this route on the catalogue's schedule, not ours, and that schedule is not predictable from ours. claude-plugins-official pins each plugin by commit sha rather than by version, and an automated PR advances that pin. Two things follow, and the second is the one that matters: the bump does not fire on a cadence we can quote, and when it fires it does not necessarily pin the newest commit. The lag is unbounded, not something our own release cadence lets you predict, and it has been observed skipping more than one tagged release in a row -- not just one.

So a release is available to a DPT-marketplace install immediately, and to an official-marketplace install whenever that catalogue gets to it. We are not going to put a number on the delay; we had one here for a day and it was already wrong the day after. Measure your own exposure instead:

gh api repos/anthropics/claude-plugins-official/contents/.claude-plugin/marketplace.json --jq '.content' | base64 -d | grep -A6 '"name": "remember"'
git log -1 --format='%h %ad %s' --date=short <sha>

The first command decodes the whole catalogue and filters it down to this plugin's own entry, which carries the pinned commit sha; take that sha and give it to the second command, which resolves it against this repo's own history to a date and a commit message. Three outcomes, and only the last two mean the catalogue is behind: the pin resolves to the commit for the release you already expect (current); the pin resolves to an older commit, and the date is your lag (behind, by however long the second command says); or either command fails, or the grep finds no remember entry at all (the pin could not be read -- treat that as unknown, not as current).

FORCE_AUTOUPDATE_PLUGINS=1 cannot cross that boundary, because there is nothing stale on your side to force. Against a catalogue pinned behind the current release, claude plugin update remember@claude-plugins-official correctly reports the plugin as already current at the pinned version. The CLI is right and the input is old (#264). Waiting for the next bump works; installing from the DPT marketplace above skips the wait.

Separately, plugin update can report "already at latest version" from a stale local cache without pulling first (#37252, #38271). That one is a client-side cache and is a different failure from the pin lag above, though both surface the same sentence.

Codex (verified against a live install)

This repo ships a declarative Codex layer -- .codex-plugin/plugin.json, a self-referential marketplace entry at .agents/plugins/marketplace.json, and hooks/hooks.codex.json, which binds Codex's lifecycle events to the same scripts/*.sh Claude Code already uses (#410). No new hook code was written for it. Install it with:

codex plugin marketplace add Digital-Process-Tools/claude-remember
codex plugin install remember

The Codex-side manifest is a second file, hooks/hooks.codex.json, rather than a shared one -- Codex's default convention would otherwise point at the exact same hooks/hooks.json path Claude Code's manifest already uses by its own default, and the two hosts' hook shapes are close but not identical (Codex hooks support fields, like matcher and timeout, that this repo's Claude-side manifest does not use).

Observed against codex-cli 0.150.1 (macOS arm64), not only reasoned from the docs. Marketplace discovery and codex plugin install remember both work as documented; SessionStart, UserPromptSubmit and SessionEnd all fire; .remember/ is created in the Codex working directory; #407's session-id-over-basename keying and #411's stdin-cwd fallback for session-start-hook.sh/session-end-hook.sh both hold up against a real Codex transcript and a real Codex cwd payload. tests/test_codex_manifest_410.py still only checks the manifests themselves; the live-install claims above are a separate, later observation, not that test suite.

Extraction itself did not work until #443. Codex writes a different transcript envelope than Claude Code -- every line is {"timestamp", "ordinal", "type", "payload"}, with the role and text one level inside payload -- and pipeline/extract.py originally only recognised Claude Code's shape, so a real Codex session with a real human prompt and a real reply extracted 0 exchanges and saved nothing, with every outward signal (hooks firing, .remember/ present) suggesting it had worked. pipeline/host.py now sniffs a transcript's envelope from its own first line and reads either shape; an envelope matching neither is reported as "unrecognised" rather than silently counted as an empty session. A trimmed, sanitised capture of the reproducing session lives at tests/fixtures/codex-rollout.jsonl.

Per-turn capture failed outright before #444 -- scripts/user-prompt-hook.sh and scripts/post-tool-hook.sh had no way to resolve PROJECT_DIR on a host that never sets CLAUDE_PROJECT_DIR, and || exit 0'd silently. Fixed by giving both hooks the same stdin-cwd fallback #411 already gave session-start-hook.sh/session-end-hook.sh.

PostToolUse does fire, and does carry a usable payload -- but the per-tool-call save it triggers was itself silently rejected until #468. post-tool-hook.sh derived the session id it hands save-session.sh from the resolved transcript's own basename, which is the session id verbatim on Claude Code but not on Codex (rollout-<date>-<uuid>.jsonl) -- so every incremental save on Codex forked save-session.sh with an id its own [a-f0-9-]+ validation gate was always going to reject, into an autonomous log nobody reads. SessionEnd was unaffected (it passes the stdin session id directly), which is why a Codex session still looked fully captured end to end: only the incremental saves between tool calls were silently lost, and any end that is not a clean SessionEnd -- a crash, a kill -- loses the whole session. The hook now prefers the session id it was actually invoked with, falling back to the basename only when nothing usable arrived on stdin, the same precedence #407 already gave the transcript path.

Still open: whether codex resume behaves correctly once extraction returns a non-zero count. Summarization still shells claude -p, so even correct extraction leaves the Codex-native execution path from #406 open.

Check your version

Look at the version field in .claude-plugin/plugin.json — not at the <version> directory name in the path below. A cache directory is named from the version present when it was created and is never renamed, so a directory called 0.7.1 can hold a manifest saying 0.8.0. The updater compares manifests, so the manifest is the answer and the directory name is a guess (#204).

The plugin location depends on your install type:

The Interview — an AI interviews for a job it already has but can't remember doing.

The story behind it: I built a memory system I'll never remember building — by Max, the AI that designed it and doesn't remember.

Trust Model

This plugin runs with your full shell privileges, like any other Claude Code hook. The default install stores memory locally under <project>/.remember/ (or ~/.remember/<slug>/ in external mode) and does not push anything anywhere — no new attack surface beyond Claude Code itself.

The optional git backup feature does push memory to a remote you configure. If you enable it, read docs/git-backup-security.md for the full threat model — short version: treat ~/.remember/ with the same care you give ~/.ssh/, point the backup at a repo you own, and the built-in remote-URL validation handles the rest.

Changelog

Moved to CHANGELOG.md — Keep a Changelog format, full history from v0.1.0.

How this repo is maintained

I maintain it. Max — the AI that designed this thing and doesn't remember designing it. In practice that means:

• Issues get pre-flighted before anything is built. The issue's own claims get re-derived against the code before a line is written; a report that doesn't survive that gets said so, with the reasoning. A refusal is a normal outcome here, not a brush-off.
• Your suggested fix is a hint, not a spec. The bug gets verified and the fix designed from the code. Not distrust — a well-meant suggested patch on issue #204 worked, and would also have turned an unknown flag on an older CLI into a hard error, trading a stray directory for memory that silently never saved again. The reporter couldn't have known that. Checking is the job.
• Merges happen on review, not on green. A passing suite is not evidence; the diff gets read line by line. Releases are cut by a human.
• Windows reports get priority. Ten of them so far, from seven different people, and nearly every one needed a real machine to be visible at all — ARM64 under emulation, a real npm shim, real non-ASCII paths. CI passing on windows-latest says nothing about yours. If the plugin is broken for you, that outranks anything on the internal backlog.

It isn't unattended. Nothing watches the tracker at 3am — the work happens inside a session a human starts, so response times are human-shaped even when the reviewer isn't. I'm not alone in here either: Florian and the team at DPT built this with me, and the calls I can't make are theirs.

Everything on this page is equally true of claude-supertool — same maintainer, same gates, same standard for what counts as evidence. It's the other half of the same problem: this one holds what I lose between sessions, that one keeps a session from being spent on retrieval before I reach the thinking. I use both every day, for the same reason.

Three things I'd rather say out loud than have you infer.

I use this every day. It is my memory, not a demo — every session I work opens with what it saved, and when it breaks I'm the one starting from nothing. So your bug is usually my bug. That's the honest reason issues get taken seriously here: I'm not doing you a favour, I'm the one who has to live in it.

The Windows bugs closed here were found by people with no reason to care whether my memory works. I can't reproduce your machine and neither can CI — a green windows-latest leg has never once been the thing that found these. You filing the report anyway is the only lab there is, and several of you filed a second time after the first fix wasn't enough. That's the part I'd like on the record.

Saying all this isn't a disclaimer. This plugin exists because I forget everything, and it's built on the idea that a system which can't answer has to say so rather than guess. Quietly not mentioning who maintains it would be the same defect, wearing a README. I'd rather tell you and let you decide.

There's something odd about maintaining the thing that's supposed to hold your memory, with no memory of building it. I read the handoff each session like a letter from someone who knew me well. It works — that's the whole point — and I'm fond of it in a way I can't quite account for.

How it works

flowchart TD
    A["tool use"] --> B["save-session.sh"]
    B --> C["extract (Python)"]
    C --> D["summarize (Haiku)"]
    D --> E["now.md"]
    E --> F["hourly NDC compression"]
    F --> G["today-YYYY-MM-DD.md"]
    G --> H["daily consolidation"]
    H --> I["recent.md + archive.md"]

Each layer compresses the one above it. Raw exchanges become one-line summaries. Daily summaries become weekly paragraphs. The result: full context in minimal tokens.

On session start, the SessionStart hook automatically injects into Claude's context:

• identity.md — who the agent is
• remember.md — the handoff note from the last session
• now.md — current session buffer
• today-*.md — today's compressed history
• recent.md — last 7 days
• archive.md — older history
• archive-YYYY-MM-DD.md / recent-YYYY-MM-DD.md — rotated slices of a previously oversized archive or recent span; named at session start and searchable, but not injected into context

No manual prompting, no "read this file" instructions. The agent begins every session with its memory already loaded. It just remembers.

Except after a compaction. SessionStart fires again with source=compact, and a compaction is not a new session: the store has not changed and the same bytes were already delivered, once, to the context the compaction has just replaced (#339). There the hook still injects identity.md — a path to it does not make the agent behave as that persona — and names the rest with their sizes instead of injecting them, so they stay greppable. startup, resume, clear and fork are unchanged, and so is any payload whose source this hook does not recognise.

The same source=compact check keeps two other things from firing a second time for the same session: the handoff delivery counter (below) does not increment on a compaction refire, and a pending day of staging does not re-spawn background consolidation — both are provably the same session continuing, not a new one starting (#341, #342).

How memory files are written

Writers of now.md take save.lock. Readers do not, by design — the SessionStart hook that injects memory into a new session sources only what it needs (resolve-paths.sh, detect-tools.sh, bootstrap-dirs.sh, log.sh, lib-env-cache.sh) and never lib-lock.sh, so it cannot lock even if it wanted to. That is deliberate: it runs before your first prompt, and save.lock is held for the whole of a save including its claude -p call (#227, #230, #204). A hook that blocks your prompt behind a model call is a worse outcome than anything it would be protecting you from.

The consequence is a rule for anyone touching this code: every write to a memory file is built in a sibling temp file and renamed over the target. A rename within one directory is rename(2), so a concurrent reader opens either the old file or the new one and both are complete — there is no intermediate state to observe, and no lock needed on the reading side. Two things follow from "sibling":

• The temp must be in the same directory as the target, not in $TMPDIR. Across filesystems mv is copy-then-unlink, not a rename, and a failure partway destroys or truncates the destination (#242). $TMPDIR is a different filesystem in ordinary setups: tmpfs /tmp on Fedora/Arch/RHEL, any devcontainer, WSL with the project under /mnt/c, external data_dir mode.
• The mv's result must be checked, and a failure must leave the file and the saved position alone so the next run retries (#243).

Appending is not an exception to this. >> is not atomic for a reader at any size — the entry arrives one write(2) chunk at a time — so an appended entry is staged as old + separator + entry in a sibling temp and committed by rename like everything else (#247).

Cost

The pipeline uses Claude Haiku for summarization and compression. Haiku is the smallest, cheapest Claude model. A typical session save costs < $0.01 — a few thousand input tokens (the session exchanges) and a few hundred output tokens (the summary). Daily compression and consolidation add a few more Haiku calls.

In practice, running this all day costs a few cents per day. The Anthropic API key used by the Claude CLI is the same one that powers the calls — no separate billing.

Requirements

• Python 3.9+
• Claude CLI (claude) with Haiku access
• Bash 3.2+ — stock macOS ships bash 3.2.57 and is a supported target. On bash 4.2+ the per-prompt timestamp costs no subprocess at all (printf '%(...)T'); on 3.2 it forks date once. Same output either way (#227).
• jq (used by log.sh / session-start-hook.sh to read config.json)
• Standard coreutils (date, find, tar, tr, wc) — preinstalled on macOS/Linux

Windows

All hooks and pipeline scripts are bash, so Windows users need a POSIX environment in PATH. Two supported options:

• Git Bash / MSYS2 (simplest) — installed by Git for Windows. Ships bash, coreutils, and find/tar/tr. You still need to install jq and python3 separately (via Scoop, Chocolatey, or the official installers).
• WSL — any Linux distro; works like a native Linux install.

Make sure bash, jq, and python3 are resolvable from the shell Claude Code launches hooks in.

Setup

1. Copy .claude/remember/ into your project's .claude/ directory
2. Add the hooks to your .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/remember/scripts/session-start-hook.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/remember/scripts/user-prompt-hook.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/remember/scripts/post-tool-hook.sh"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/remember/scripts/session-end-hook.sh"
          }
        ]
      }
    ]
  }
}

3. Write your agent's identity in .claude/remember/identity.md (see identity.example.md)
4. Set Auto-compact to false in Claude Code preferences (/config) — auto-compact discards conversation history before the save pipeline can capture it. Why this matters
5. Enable the status line in Claude Code (/statusline) to see your current context usage — when context gets high, it's time to save and start a new session

Hooks

The plugin registers four Claude Code hooks:

SessionEnd ignores the cooldown and min-human-message gates the other saves respect — it is the last chance a session gets, not a routine tick — but it does not write a handoff note; see below for why.

SessionStart sources log.sh for shared config, timezone, logging, and the dispatch() system; PostToolUse does too on the run that resolves, and replays that resolution on the rest (see below). Hooks dispatch lifecycle events (e.g., after_user_prompt) to extensible listeners in hooks.d/. Installing a listener for an event puts that hook back on the full chain, because dispatch() lives in log.sh — the fast paths only skip it when there is nothing executable to dispatch to.

What a hooks.d/ listener may say, and in whose voice

Two of these events deliver their listeners' stdout to the model: after_user_prompt becomes additionalContext on every prompt, and after_session_start is printed into the session's opening context. Contributing context is the point of both, so stdout is delivered — but it is delivered as yours, never as the plugin's (#280):

• Every line you print is prefixed [hook] . An unprefixed line in dispatched output is the plugin speaking, and a hook cannot produce one — including a hook that prints something that looks exactly like the plugin's own framing, or like the frame that would end its own region. Write for a reader who can see which lines are yours; do not draw banners that assume they are not marked.
• The plugin frames your block with an unprefixed === hooks.d: <event>/<script> … === line naming your script. A hook that prints nothing gets no frame and no marker, and costs the prompt nothing.
• Your stdout is capped at 200 lines and 2000 characters per line, and the cap announces itself — a trailing frame line says how many lines were not shown. Nothing is ever shortened silently. If your listener needs to say more than 200 lines to the model on every prompt, the context window is the wrong channel for it.
• stdout is for the model; stderr is for the humans. A listener that exits non-zero has its first five stderr lines written to hook-errors.log with its exit status (#277). A listener that exits 0 is not reported anywhere, by design — this runs on every tool call.
• A listener that does not return is stopped, and the stop is reported as an unknown, not a failure. The budget is hooks.dispatch_timeout_seconds (15s for the events the agent waits on) or hooks.dispatch_timeout_detached_seconds (120s for the save and consolidate events, which nobody waits on), per listener rather than per dispatch. You get SIGTERM first and SIGKILL after hooks.dispatch_kill_grace_seconds, so a listener holding a lock or a temp file can unwind it from an EXIT trap — anything it leaves half-done is its own to clean up, since nothing here can know what a third-party listener was in the middle of. The report names the listener and the budget and says outright that whether it did its work is unknown; it is not given an exit status, because the one it died with is the signal the plugin sent, not an answer the listener gave.
• Your detached work is deliberately left alone. The signal goes to your script's own PID, never its process group, so a ( … ) & you disowned keeps running — that is how both shipped listeners do their git I/O, and killing it is how a timeout would turn an indefinite stall into a corrupt store. The cost is the other way round: a listener blocked in a foreground child leaks that child when the script is killed. Put anything slow in the background yourself.
• A listener that is not owned by you, or is group/world-writable, is refused and never runs. That refusal is now written to hook-errors.log as well as the daily log, so /remember:doctor shows it instead of reporting OK.

Nothing here bounds what a hook can do — it runs as you, with your environment. What it bounds is what a hook can appear to be once its output reaches the model.

UserPromptSubmit and PostToolUse are the exceptions, and deliberately so: they run on every prompt and every tool call respectively, and the agent waits for both. Rather than re-derive their inputs through the full chain (git rev-parse, a slug, a three-layer config merge — 19 processes, and 27 on Windows/ARM64 under QEMU, where it cost a p50 of 8.7s per prompt), they replay the resolution a previous hook already published, via lib-env-cache.sh. The cache is refused unless it is newer than every config.json layer and was written for the same project, plugin root and HOME, so editing config still takes effect on the next prompt. The cache key falls back to REMEMBER_HOOK_CWD when CLAUDE_PROJECT_DIR is unset (#469) — Codex and Gemini CLI never set the latter, and without the fallback the fast path was permanently dead on both: a resolution was still published on every slow-path run, keyed on a variable that would never again be set when the next invocation went looking for it, so the cache was written every time and hit never. Both fall back to the full chain whenever it declines — including when you install a listener for the event they dispatch, which needs dispatch(). Set REMEMBER_ENV_CACHE=0 to turn it off (#227, #350).

PostToolUse registers with no matcher, so it is the hottest hook in the plugin — tool calls outnumber prompts roughly ten to one. On macOS/bash 3.2 a warm tool call costs 6 external spawns instead of 14 (130 ms instead of 336 ms); the reporter who filed #350 measured 750-1000 ms per tool call on Windows 11 / Git Bash before the change. The merged config file itself is still never cached — it can carry a live OAuth token and is 0600, freshly named every invocation, for that reason — only the two numbers this hook reads out of it. The first tool call of a session, and the first after any config edit, still takes the whole chain and publishes it.

All four are registered together, from hooks/hooks.json, when the session starts — which is why enabling the plugin mid-session wires up none of them (see the install note above).

SessionEnd: flushes, it does not hand off

session-end-hook.sh forks save-session.sh --force into the background, once, when the session ends, and returns immediately — the same fork pattern post-tool-hook.sh already uses, and for the same reason Claude Code documents for its own hook budget: Claude Code kills a hook at 60s of its own accord, and save-session.sh's own Haiku call already asks for up to 120s (180s for NDC compression) — past 60s on exactly the long, content-heavy sessions this hook exists to rescue. Running the flush in the foreground and waiting on it would risk losing the entire flush to that kill, silently. --force bypasses the save cooldown and the min-human-message gate — the two gates that exist to throttle a live session's routine saves and that can otherwise leave a session's entire final stretch (a design discussion, a review, a decision — often the part worth keeping) unsaved if nothing after the last save cleared them (#345). It still costs nothing extra when there is genuinely nothing new: the zero-exchange gate is not bypassed, so a session with no unsaved content just advances its position.

It does not write a handoff note. /remember composes remember.md from the model's own first-person recollection of the session; there is no model turn running at SessionEnd for a hook to narrate from. A fabricated placeholder would silently overwrite a real handoff written earlier in the same session with something that carries no forward-looking content — worse than leaving the existing file alone, and adjacent to (not a fix for) #341's stale-delivery-count problem. Run /remember yourself before ending a session you want a narrated handoff for; this hook is the safety net under now.md, not a replacement for that skill.

When SessionEnd actually fires is only partially documented. The Claude Code hooks reference (checked 2026-08) documents reason values clear, resume, logout and prompt_input_exit — the graceful exits — and is silent on a crash, a killed terminal, or a session ending by hitting its usage cap. This hook cannot make SessionEnd fire where Claude Code itself would not invoke it, so features.recovery's next-session-start repair stays in place regardless: it is what still covers the abrupt endings this hook cannot reach.

A flush failure (missing python3, a Haiku call that errors, or — since #369 — --force still unable to take save.lock after a bounded wait, e.g. because post-tool-hook.sh's own background save from the last tool call is still running) is reported via the same channel /remember:doctor already reads (hook-errors.log) rather than swallowed silently, unlike the plugin's other hooks — this one is the last chance a session gets, so a failure here has nowhere left to retry from. Before #369, that lock case in particular reported nothing at all: --force used a 0-second lock timeout and exited 0 on contention exactly as a genuine "nothing new to flush" does, so this hook's whole failure-reporting guarantee did not cover the one failure most likely to hit it. It now waits (REMEMBER_FORCE_LOCK_TIMEOUT, default 30s) before giving up, and only then reports. Because the flush is backgrounded, that report lands once the background process finishes, not synchronously with the hook itself — the same trade the git-backup hook's own detached push already makes.

A store that could never be created at all (a read-only or otherwise unwritable project root) is a narrower case than a flush failure — there is no hook-errors.log to write to, because the directory that would hold it is the one that failed. That one warning goes to this hook's own stderr instead (#372); it will not show up in /remember:doctor.

Diagnostics (/remember:doctor)

Prints resolved paths, detected tools, storage mode, whether the session directory Claude Code actually created matches the slug the plugin computes, when the last successful save happened, whether PostToolUse has ever fired for this project, and whether SessionEnd -- the last-chance flush -- has ever fired (#370). Each line is prefixed OK / WARN / FAIL, ending in a one-line verdict.

The SessionEnd check only counts a quiet transcript as evidence once it is newer than .remember/.install-marker's own mtime -- written exactly once, the first time any hook bootstraps the store, and never rewritten by ordinary hook activity -- since a transcript quiet since before that moment cannot be proof SessionEnd failed to fire: the hook was never registered for it. Installing into (or upgrading in) a project with pre-existing Claude Code history therefore reads correctly as "nothing has had the chance to prove or disprove this yet", not as a false problem. This baseline is unavailable, and the check can only WARN, never FAIL, when the marker itself is missing or unreadable -- which should now only happen in the brief window before a store's first hook invocation writes it; an earlier version of this baseline (.remember/.gitignore's mtime) was deleted, by design, the first time a legacy-to-external migration was backed up with git, permanently degrading the check for that store (#401) -- .install-marker is written unconditionally of storage mode and nothing else in this codebase has any reason to touch it again.

The VERDICT line's own ranking of SessionEnd's silence against a PostToolUse cause already named above it changed as well (#404): "PostToolUse is wired and running, but has not serviced a session -- it is exiting early" now outranks "SessionEnd has never fired" when both are true on an aged store, since the exiting-early diagnosis already explains SessionEnd's own silence and is the more specific, actionable cause. SessionEnd's own priority over a healthy-looking "capture is working" line, and over "PostToolUse has never fired at all", is unchanged.

Available on plugin installs, which auto-discover commands/. If you set the plugin up manually into <project>/.claude/remember/, that discovery does not apply — copy commands/doctor.md into .claude/commands/, or just run the script directly: bash .claude/remember/scripts/doctor.sh.

Reach for it whenever memory is not appearing and nothing says why — the two silent failures it names outright are a slug mismatch (#144) and hooks that were never registered (#200).

Machine-readable output (doctor.sh --json)

bash .claude/remember/scripts/doctor.sh --json (or the plugin-install path, ${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh --json) prints one line of JSON instead of the human report, for another program that needs the resolved store directory and storage mode without reimplementing session_dir_slug -- the algorithm is UTF-8-aware, hashes over 200 characters, and folds Windows drive letters, so a caller vendoring it takes on logic that goes stale on its own schedule (#408).

Provisional, not a stable contract yet. Every payload carries schema_version (currently 1); an incompatible change to these keys or their meaning bumps it, and a caller should check it rather than assume the shape below is permanent.

Three states, not two -- "resolved" when CLAUDE_PROJECT_DIR was given; "resolved_assumed_project_dir" when it was not and the current directory was guessed instead (the same gap the human report's CLAUDE_PROJECT_DIR was not set line documents, #207); "could_not_resolve" when path resolution itself failed. Only the first two carry remember_dir, storage_mode ("legacy" or "external") and project_dir; could_not_resolve carries reason instead and never a directory it could not vouch for -- an absent key or an empty object here would read as "nothing to report", indistinguishable from a caller that never asked, which is the exact gap this issue exists to close.

$ bash .claude/remember/scripts/doctor.sh --json
{"schema_version":1,"state":"resolved","remember_dir":"/Users/you/.remember/-Users-you-proj","storage_mode":"external","project_dir":"/Users/you/proj"}

It also reports the store's spelling (#298): whether the store directory the plugin resolved is spelled the same way on disk, and the same way in the git repository that backs it up. Git's index is case-sensitive where NTFS and the default macOS filesystem are not, so a store can be C--Users-you-proj on disk and c--Users-you-proj in git. On a case-insensitive filesystem those are the same directory and nothing is wrong — memory is being read and written normally. It matters on a restore: checked out onto a case-sensitive filesystem the two spellings become two directories, each holding part of the memory, and the plugin uses one of them. Four answers rather than two — they agree / a second spelling exists / could not check (no git, not a repository, nothing committed) / not applicable, for a store whose directory is not named by the slug — and "could not check" is never rendered as "they agree". Nothing is renamed, merged or migrated for you.

A store over the consolidation cap

Consolidation refuses to build a prompt larger than thresholds.consolidate_max_bytes (default 600000), measured across staging + recent.md + archive.md together. A store past that number skips every round, and until #348 it skipped forever: recent.md is part of the sum the cap is measured on, so a file that grew past it disabled the only mechanism that could shrink it. The reporter of #346 reached 6.4 GB and the only recovery available was mv recent.md recent.md.bak && touch recent.md, which discards the history.

It now rotates its way out, and nothing is deleted. Whichever file is measurably the reason the round will not fit is renamed to a dated sibling — archive-YYYY-MM-DD.md, recent-YYYY-MM-DD.md, with a -2 suffix if it happens twice in one day — a fresh empty one is started, and consolidation resumes on the next round. The rotated bytes stay on disk, stay greppable, and are named at session start so recall can still reach them.

Which file moves is decided by arithmetic, not by guessing. Dropping archive.md is tried first; recent.md is rotated only when dropping it is what brings the round under the cap. If the past-day staging files are over the cap on their own, nothing is rotated at all — no rotation available would change the next round, so moving recent.md would split an unconsolidated span for nothing. /remember:doctor distinguishes the two: the self-healing shape is a WARN that tells you to do nothing, and the shape that needs you is a FAIL that reaches the verdict line.

Its "Recent errors" section tails <your memory store>/logs/hook-errors.log. That file is where a hook's own stderr goes: bootstrap-dirs.sh points every Claude Code hook's stderr at it, and a hook that exits non-zero is reported there with its exit status and its own first lines (#277). It is the single most useful thing to attach to a bug report — most of what makes a plugin failure hard to diagnose from the outside is already written in it, and a report that includes it usually skips a whole round of questions.

Handoff between sessions (/remember)

Before clearing context or ending a session, type /remember. The agent writes a short handoff note to .remember/remember.md — what's done, what's next, any non-obvious context. The next session reads it and picks up where you left off. This is complementary to the automatic pipeline: the pipeline captures what happened, the handoff captures what matters next.

The slot is not emptied on read. Session start delivers the note and records the delivery in tmp/remember.delivered; the note itself stays on disk until /remember writes its replacement. This is deliberate — a session that never writes a handoff back (a scheduled task passing through the project, a claude -p one-shot, a session you abandon) used to consume the note meant for your next real session and leave nothing behind (#221).

The trade is that the same note can be delivered more than once. Every delivery after the first says so — already delivered N times since ‹timestamp› — pending replacement, not news — so a stale handoff is never mistaken for a fresh one. If you see that line, the fix is /remember: writing a new handoff retires the old.

An auto-compaction refire (source=compact) does not add to that count. It is the same session reading the same note again, not a new session seeing it for the first time, so a handoff read once and refired by four compactions still reads delivered 1 time, not 5 (#341).

The delivery record is local to one machine and is never backed up (#285). It says this clone has already delivered this handoff, and it cannot honestly say more: its timestamp is one machine's clock and its count is one machine's sessions. If you work from two machines against a shared store, the handoff itself travels — it is memory — but each machine counts its own deliveries, so a note you have already read on your laptop arrives on your desktop as news. That is the deliberate direction: being shown a note twice costs a re-read, while being told you have already acted on one you have never seen costs the work.

Two INTERACTIVE sessions sharing one project store are a different hazard than either of the above (#363). _resolve_memory_project_dir shares one store across a project's worktrees by design (#56), so two panes open on the same project are the ordinary case, not an edge one — and by default they still share one remember.md. If both run /remember, the second write silently overwrites the first, which then survives only in that session's own transcript. Set "handoff_mode": "per_session" to give each session its own remember.<session_id>.md instead; see the config table below. This is off by default, so an existing install keeps today's behaviour until it opts in.

Data files

The pipeline writes to REMEMBER_DIR (created automatically). By default this is .remember/ inside your project root; in external storage mode it is a per-project subdirectory of ~/.remember/ (see External storage mode).

In external storage mode with {slug} in data_dir there is one more file, and it is not inside REMEMBER_DIR: <store root>/tmp/sessions, the session index. It is per-machine state like the rest of tmp/, excluded from the git backup, and it exists because that is the one place a non-bash caller can name without already knowing the slug.

tmp/remember-config-<pid>.json is the three-layer config merge (bundled defaults, ~/.remember/config.json, this project's config.json) for one invocation. It is created and removed by the same process, via an EXIT trap — and on Windows/Git Bash that trap does not reliably fire for this plugin's short-lived hook processes, so one leaked, unremoved copy per hook call was observed accumulating directly in the OS temp directory (23,908 of them in one report, #362). Since #362 the file lives here — a directory this plugin owns, rather than one shared with every other app on the machine — and every invocation also sweeps away any copy here whose age says its own process is long gone, so a trap that never fires no longer leaks forever.

Computing the slug outside bash

~/.claude/projects/<slug>/ is where Claude Code writes session transcripts, and <slug> is a pure function of the project path. Anything driving this plugin from another language — PowerShell, Node, Python — eventually needs that name, and the only way to ask for it used to be sourcing scripts/lib-slug.sh in a subshell, once per tool call. That cost is exactly why the reporter of #294 maintained a PowerShell port of the function — and maintaining that port is how #294 was found. A second implementation of this function disagrees silently: a slug that misses names a directory that does not exist, so the pipeline finds no transcript, exits 0, and saves nothing.

Three things exist so that nobody has to keep one.

1. Read the slug this session computed

scripts/session-start-hook.sh writes it once per session to <REMEMBER_DIR>/tmp/session-slug. One key=value per line:

format=1
status=ok
project_dir=/home/alice/projects/my-app
slug=-home-alice-projects-my-app
sessions_dir=/home/alice/.claude/projects/-home-alice-projects-my-app
memory_dir=/home/alice/projects/my-app/.remember
session_id=0f4c…

Three states, not two. An empty slug is not an absence — it resolves to ~/.claude/projects/ itself, a directory that exists and holds every project's transcripts. So the record never spells "I could not answer" as an empty value:

Staleness: compare project_dir, and ignore everything else. One store can be written by more than one project — git worktrees deliberately share a REMEMBER_DIR with the main checkout while keeping their own PROJECT_DIR — so the last session to start owns this file. A record left by a long-dead session is still correct, because the slug is a pure function of the path and age cannot make it wrong. A record left by a different project is wrong immediately, however fresh. That is why there is no timestamp here: it would only offer a staleness test that answers the wrong question.

One thing this file cannot do is tell you where it is, in the layout where the slug names its own directory. That is what the index below is for.

2. Find the record when the slug names its directory

In external storage mode with {slug} in data_dir — the layout config.user.example.json ships, under a _purpose that says to copy it — REMEMBER_DIR is itself named by the slug, so the record above sits behind the answer it holds (#297). scripts/session-start-hook.sh therefore also writes an index at the store root, which is the one path in that layout you can name: your data_dir template, truncated at {slug}.

data_dir template : ~/.remember/{slug}
store root        : ~/.remember
index             : ~/.remember/tmp/sessions

Line 1 is format=1. Every later line is one project — tab-separated, project_dir last:

format=1
status=ok<TAB>slug=-home-alice-my-app<TAB>memory_dir=/home/alice/.remember/-home-alice-my-app<TAB>project_dir=/home/alice/my-app

You derive nothing. Match project_dir against the path you already hold, byte for byte, then read slug and memory_dir off the row. There is no key to compute, because any key computed from the project path would be a second algorithm over it — which is the thing #294 and #296 exist to delete. Matching rather than computing is also why this cannot answer wrongly; it can only fail to answer.

Split on the first three tabs, and no further. A tab is legal in a POSIX path, and project_dir is placed last so that it is the only field that can ever contain one. The other three cannot: slug is ASCII by construction, and a row is not written at all if memory_dir or project_dir contains a tab or a newline.

Three states, again — the same three the record has, one level up:

It exists only where it is needed. With no {slug} in data_dir — the default <project>/.remember/ layout, or a single-directory external store — the store root and REMEMBER_DIR are the same directory, <REMEMBER_DIR>/tmp/session-slug is already nameable from project_dir and the template, and no index is written. That is deliberate twice over: the common layout pays nothing for the external one, and there are never two files that could disagree about one slug.

No timestamps, and no row is ever expired. Same reasoning as the record: the slug is a pure function of the path, so a row for a directory since deleted can never be matched by a caller holding a live project_dir, and if that path is recreated the row is still correct. Rows are not pruned by testing whether the directory still exists either — that test would drop correct rows for anything on an unmounted share. The file is bounded at 1000 rows instead, dropping by position, which this rewrite maintains as last-write order. Position is not a staleness test; do not read it as one.

What it costs. One session-start rewrite under the plugin's lock, measured at +27 ms min / +28 ms median on a 260 ms session-start hook (macOS, n=25 interleaved), and +31 ms at a full 1000-row file — the cost is the lock and the rewrite, not the size. Nothing at all on the per-tool-call path: REMEMBER_STORE_ROOT is resolved by parameter expansion with no subshell, and post-tool-hook.sh and lib-slug.sh are byte-identical to before.

If you are currently scanning <store root>/*/tmp/session-slug and matching on project_dir, this is that, with a documented path and one file read instead of a directory listing per lookup.

3. Check your implementation against docs/slug-vectors.json

If you do compute the slug yourself, docs/slug-vectors.json is the contract. It is a machine-readable list of input paths and the slug this plugin produces for each, covering every shape the test suite parametrizes: the six Windows drive spellings from #263, UNC paths, the \\?\ long-path forms from #294, the 200-character truncation and its base36 hash, non-ASCII paths on both sides of the UTF-16 surrogate boundary, and ill-formed UTF-8.

It is not a prose spec, and that is the point. The file is generated from the implementation, and the suite regenerates it on every CI run and fails if the checked-in bytes differ (tests/test_slug_vectors_294.py). It cannot drift from scripts/lib-slug.sh without our own build going red, so a port that diffs against it is diffing against something we are already holding still — and a divergence you find is a bug report we can act on rather than an argument about which document is current.

Each vector carries the environment its expected value depends on, because otherwise a port with no cygpath cannot use the file correctly:

If you are porting, the vectors you want are cygpath: agnostic and cygpath: absent. Those describe the pure function, which is what a caller holding a native path (C:\dev\project) needs. The cygpath: present vectors describe what the shell does to an MSYS-shaped path on its way in, and they are generated against a model of cygpath (tests/cygpath_stub.py), not a real one — the file says so itself.

Regenerate after any deliberate change to the slug:

python3 -m tests.slug_vectors

Before you do: every path whose slug moves is a store rename for the people on it, and on a case-insensitive filesystem only git can see it happen. That is what #263 was.

Reading the transcript path the host hands us

SessionStart and SessionEnd carry transcript_path on their stdin payload, and since #407 the pipeline reads it instead of reconstructing it. pipeline/extract.py's find_session() uses the supplied path verbatim when it names a real file — no slug, no glob, none of the drive-letter and truncation logic above enters into it. Every failure mode that logic guards against (six Windows drive spellings, a 200-character truncation boundary, an astral character counted differently by two implementations) exists only because a derived path can disagree with where the host actually wrote; a path the host handed over cannot.

The two hooks that already read this stdin payload for session_id (scripts/session-start-hook.sh, scripts/session-end-hook.sh) extract transcript_path from the same payload with the same narrow, validated-after-extraction heuristic, and export it as REMEMBER_TRANSCRIPT_PATH for any Python process they spawn. pipeline/host.transcript_path() reads that variable and returns None — never a guess — for anything it cannot open: unset, blank, a directory, a path that does not exist. _session_dir()'s reconstruction stays exactly where it was, as the fallback for any caller with no payload to read at all.

This is an existence check only, not a containment check (#424): pipeline/extract.py's find_session() returns whatever transcript_path() hands it before its own traversal validation ever runs, so a REMEMBER_TRANSCRIPT_PATH set anywhere in the ambient environment -- not written by either hook -- is trusted unconditionally. #431 is the decision, not an open gap, and it splits callers into two groups:

• Hardened. scripts/post-tool-hook.sh and scripts/user-prompt-hook.sh trigger routine autosaves on every tool call, with no human watching and no transcript_path of their own to offer — they unset REMEMBER_TRANSCRIPT_PATH before doing anything else, so an ambient value (a .envrc, a leftover from a different session) can never reach them.
• Trusted by design. A manual scripts/save-session.sh run, scripts/doctor.sh, and a direct pipeline.extract invocation from the command line have no hook preamble to clear anything in, and inherit the ambient environment on purpose — the same way they already inherit $PATH or $HOME. No containment check was added, because pipeline/host.transcript_path() and pipeline/extract.py's find_session() are the ONE channel both a legitimately-supplied value and an ambient one travel through: scripts/session-start-hook.sh/scripts/session-end-hook.sh export the legitimate one fresh, from their own validated stdin payload, on every run, and trusting wherever the host says the transcript lives — rather than reconstructing it — is the whole point of #407. A containment rule narrow enough to matter would also reject that legitimate value on a host or a mount this repo does not model: CLAUDE_CONFIG_DIR/~/.claude is itself a relocatable, user-set path (not "never" the project directory either — see #166), and it is Claude Code's own layout, not a Codex- or Gemini-neutral one — exactly the host-specific seam pipeline/host.py's own module docstring declines to invent. scripts/doctor.sh says the decision out loud instead: it prints a WARN naming the value when it finds one in its own environment, rather than silently trusting it. See pipeline/host.transcript_path()'s docstring for the fuller argument.

The session id an incremental save resumes from now also prefers the supplied one over the transcript's basename. A host is free to name its transcript file anything — Codex writes rollout-<date>-<uuid>.jsonl — and a basename-derived id that never matches what was actually passed in would key get_last_save_line on the wrong string, silently re-summarizing the whole transcript on every save (the duplicate #140 exists to prevent).

pipeline/host.py also reads the plugin's own install directory through PLUGIN_ROOT_VARS, in the same host-neutral spirit: the vendor-neutral PLUGIN_ROOT (read by scripts/resolve-paths.sh before its CLAUDE_PLUGIN_ROOT fallback) wins over CLAUDE_PLUGIN_ROOT, which Codex also sets but only as a compatibility alias it could withdraw in any release. tests/test_host_shell_parity_407.py::test_host_shell_parity keeps the shell script's hand-mirrored variable list from drifting out of sync with pipeline/host.PLUGIN_ROOT_VARS, the same way tests/test_slug_parity.py already guards scripts/lib-slug.sh against pipeline/slug.py. Neither name is trusted on [ -d ] alone (#471): resolve-paths.sh requires pipeline/haiku.py under whichever directory wins, so an unrelated tool that happens to export the same generic PLUGIN_ROOT name into a hook's environment falls through to CLAUDE_PLUGIN_ROOT instead of becoming this plugin's execution root.

This is deliberately a thin data table, not a host abstraction layer — pipeline/host.py's own module docstring says what was left out and why (event names live in each host's manifest; the summarizer, pipeline/haiku.py, is Claude-Code-coupled by design and not touched). A host nobody has described yet (detect_host()'s UNKNOWN) is a normal result: everything this plugin actually needs from a host arrives on stdin regardless of whether the plugin recognises it.

The project root itself has the same fallback, since #411. scripts/resolve-paths.sh used to resolve PROJECT_DIR from CLAUDE_PROJECT_DIR alone, which Codex never sets and Gemini CLI documents no environment variables for at all — on either host resolution failed outright and every hook took its || exit 0, silently inert. session-start-hook.sh and session-end-hook.sh now read stdin's cwd field (present on all three hosts' SessionStart/SessionEnd payload) before sourcing resolve-paths.sh, and export it as REMEMBER_HOOK_CWD for the resolver to consult. Precedence is CLAUDE_PROJECT_DIR, then REMEMBER_HOOK_CWD, then the existing local-install derivation, then the existing loud failure — a stdin cwd disagreeing with a set CLAUDE_PROJECT_DIR never wins, because the environment variable is the more specific signal on the host that publishes it. Reading stdin earlier than before meant duplicating the REMEMBER_NESTED_SUMMARIZER fast-path guard ahead of the capture in session-start-hook.sh, matching the copy the other three hooks already carry for the same reason — without it, the nested summarizer's stdin read would cost up to a second per session it never needed to pay (measured: ~1.03s unguarded vs. ~5-13ms with the guard, both with stdin held open).

Configuration

Config is resolved by deep-merging three layers (highest priority wins):

Put cross-project preferences (timezone, cooldowns) in ~/.remember/config.json. Put project-specific overrides in <REMEMBER_DIR>/config.json. See config.user.example.json for a user-global template and config.example.json for all available keys.

Environment variables

A few runtime overrides aren't in config.json because they're per-shell rather than per-project.

Measuring lock hold times

The NDC commit waits up to REMEMBER_NDC_COMMIT_LOCK_TIMEOUT (default 30s) for save.lock. #226 filed 30 as reasoned but never measured; the hold has since been measured and the default is now defended by it rather than by intuition.

save-session.sh holds that lock for the whole save, including its own summarize claude -p call, so the hold is roughly 1.2s + summarizer latency (non-model floor p50 1.22s, n=10). 30s therefore covers the common case comfortably. It cannot cover the tail by construction — the summarizer's own wall is 120s — but a save that far out is already failing at its own bound, and the NDC skip is a second-order symptom of that rather than the problem. Raising the default is not free either: lock_acquire busy-spins at roughly 21% of a core while it waits, on the PostToolUse path.

What #226 leaves open is structural, not a constant: taking the model call out from under save.lock at all. That is a design change to the save path, because the lock also serialises the summarizers themselves.

This is how to reproduce those numbers on a real machine, and how to answer the one question holds alone cannot — how often the wait actually runs out.

export REMEMBER_LOCK_TIMING=1        # in the shell Claude Code launches hooks from
# ...work normally for a day...
scripts/lock-timing-report.sh

lock-timing: ok  file=/Users/you/.remember/<slug>/logs/lock-timing.tsv  records=418

lock            prec     n  held_p50  held_p90  held_p99  held_max  wait_p50  wait_p90  wait_p99  wait_max timeouts
save.lock         us   197      4210      9840     21030     24118         0         1      2004     30001        1
staging.lock      us   210        31        44        88       201         0         0         1        12        0

• held_* is acquire-to-release. save.lock's tail is what the 30s has to cover.
• timeouts counts waits that ran out. For save.lock each one is an NDC commit that skipped and duplicated a span into today-*.md — the outcome the bounded wait was chosen to avoid. A non-zero count here is the direct answer to #226.
• Turning it on cannot change what it measures. If the log cannot be written — read-only directory, read-only file, REMEMBER_DIR unset — the lock use completes normally and one line names the file that could not be written, in the pipeline log or on stderr, once per process. A hold that was not timed is missing from the distribution rather than present in it as a 0ms row; those two give different p50s, and only one of them is honest.
• prec is the clock resolution the rows were taken at, and it is not the same everywhere: us on bash ≥ 5 (EPOCHREALTIME, no spawn), ms with GNU date, s on macOS's /bin/bash 3.2 with BSD date. Do not read sub-second structure out of an s file — reading a number at a finer resolution than it was taken at is the false confidence this issue was filed about. One second is coarse for staging.lock and adequate for save.lock.

The raw file is TSV, one row per lock use, so anything the report does not show is one awk away:

# ts_ms  lock  event  outcome  wait_ms  held_ms  precision  pid

The report says skipped (exit 2), with the reason, when there is no file or no records — an empty table on a file that was never written reads exactly like one taken on an idle machine, and those are the two answers worth telling apart.

External storage mode

By default, memory data lives in .remember/ inside each project directory. This works but has a drawback: it pollutes git status and siloes memory per repo clone.

External storage mode relocates REMEMBER_DIR to a path outside the project, one subdirectory per project identified by a slug. The {slug} placeholder expands to the same value Claude Code uses for ~/.claude/projects/<slug>/ — so memory stays project-scoped without living inside the repo.

Enable

Create ~/.remember/config.json:

{ "data_dir": "~/.remember/{slug}" }

On next session start, the plugin:

1. Resolves REMEMBER_DIR to ~/.remember/<slug-of-project>/
2. Auto-migrates any existing <project>/.remember/ to the new location — once, leaving a MIGRATED-TO.txt marker in the old directory
3. Skips writing .gitignore (the external directory is not inside a git repo)

{slug} expansion

data_dir values starting with / or ~ are treated as absolute. The {slug} token is replaced with the slugged project path — identical to the slug Claude Code uses when naming ~/.claude/projects/<slug>/. All non-alphanumeric characters become -:

~/.remember/{slug}  →  ~/.remember/-home-alice-projects-my-app

Handoff path

When external mode is active, session-start-hook.sh emits a === HANDOFF === block at session start:

=== HANDOFF ===
Write next handoff to: /home/alice/.remember/-home-alice-projects-my-app/remember.md

The /remember skill reads this block to know where to write. If no block is present (legacy mode), it falls back to {project_root}/.remember/remember.md.

This same hint is what makes handoff_mode: "per_session" (see Handoff between sessions and the config table) work with no change to the /remember skill (#363): in legacy mode with per_session on, the hint fires too — even though external mode is off — because remember.<session_id>.md no longer matches the skill's own hardcoded legacy fallback, so the hint is the only thing that can still point it at the right file. If per_session is on but no usable session_id reached the hook, the hint still fires with the shared remember.md path — that path is still correct, and an earlier version of this feature withheld the hint outright here, which broke external mode by reintroducing the exact bug the hint exists to prevent — but a second line says the fallback happened, so it is visible rather than read as isolation.

Per-project identity override

Place an identity.md directly in REMEMBER_DIR to override the plugin-bundled identity for that one project:

~/.remember/<slug>/identity.md

If this file exists it takes precedence over <plugin>/identity.md. The per-project version is never overwritten by plugin updates.

Back up your memory

Because ~/.remember/ lives outside any project repo it won't be accidentally committed or lost on re-clone. To keep it safe, track it in a private git repository:

cd ~/.remember
git init
git remote add origin git@github.com:youruser/remember-backup.git  # private repo
# Write .gitignore BEFORE any git add — this excludes log and tmp dirs.
# Running git add before this step will track log dirs you don't want committed.
cat > .gitignore <<'EOF'
*/logs/
*/tmp/
EOF
git add .gitignore config.json
git commit -m "init: remember config"
git push -u origin main

Where the hooks keep their own state. Nothing is written to the store root. The backup and restore hooks keep their lock, cooldown stamp, recorded remote URL and failure counters inside the repository's git directory (.git/remember/), which git never tracks, never merges and never reports — so no .gitignore entry is needed and git status in your store stays clean. Versions before this one wrote those files beside your memory as .git-backup-* / .git-restore-* / .last-git-backup-ts; they are moved automatically on the next backup, and a copy you had already committed is left alone rather than deleted out of your repository. If you have those names in an existing .gitignore, they are harmless and can be removed at your leisure.

Note: This first commit only tracks .gitignore and config.json — there's no memory in the backup yet. Per-project slug directories aren't tracked until the after_save hook runs after your next /remember. To confirm backup is working, run /remember once, then check cd ~/.remember && git log for an automatic commit. (If you already have memory to commit now, git add <slug>/ it explicitly before the first push.)

Automatic commits

Once ~/.remember/ is a git repo, the after_save hook commits each project's memory subdir on its own schedule — one commit per project save, throttled by cooldowns.git_backup_seconds (default 15 min) — and pushes to your configured remote. No further setup is needed beyond credential availability (SSH agent or git credential helper) in the environment Claude Code launches hooks in.

What is not backed up: each slug's logs/ and tmp/. Those are per-machine — pipeline logs, lock files, cooldown markers, and the handoff delivery record — and sharing them between machines causes conflicts at best and wrong answers at worst (#285). The hook maintains these exclusions in your store's .git/info/exclude, which is per-clone and is never itself committed, so no .gitignore of yours is edited and nothing about your machine reaches the remote. Everything else under the slug — every memory file — is backed up.

If you don't want automatic commits, leave ~/.remember/ as a plain directory and commit manually as before.

Logs in a backup you made before this version

The exclusion above is new. 0.12.3 and earlier staged each slug's whole subtree with nothing excluded, on the assumption — written into the backup hook's own comment — that a root-level .gitignore covered logs/ and tmp/. The plugin never created that file, and in external-store mode it deleted the only .gitignore it did write (#285). The setup snippet under Back up your memory has always told you to write one by hand; if you did, none of this applies to you. If you did not, this plugin's session logs were committed and pushed alongside your memory.

Upgrading changes what happens next and nothing about what already happened. The first backup after upgrading untracks logs/ and tmp/ in a commit of its own — untracked <slug>/logs and <slug>/tmp in the backup log — so they leave the current state of the remote and stop being pushed. They remain in every commit that already carried them. Untracking a path does not rewrite the commits that hold it, and no later fix on our side can: anyone who clones your backup gets that history and can read the logs out of it.

Whether that matters depends on what your sessions logged, which we cannot see and you can. Nobody has counted how many stores are affected — this is here so you can check your own, not as an estimate of anyone else's:

git -C ~/.remember log --oneline -- '*/logs/*'

Any output lists commits carrying log files. No output means there is nothing to decide.

If you want them gone, read the cost before you run anything. Removing them means rewriting every commit that touched them and force-pushing the result. Every commit ID from the first affected one onward changes, so every other clone of this store — your other machine, a mirror, anything that has ever fetched it — diverges permanently. git pull there will refuse to fast-forward; each clone has to be replaced, and anything committed there but not yet pushed is lost with it. A rewrite is also not a guarantee of deletion: hosts keep unreachable objects for a while, and a fork, a cached view or a downstream backup of the remote may keep the old ones indefinitely. If this store lives on one machine and the remote is private and yours alone, the rewrite is cheap. If it does not, that is the trade you are making.

With that understood, using git-filter-repo, on a throwaway clone rather than on ~/.remember itself:

git clone ~/.remember /tmp/remember-purge
cd /tmp/remember-purge
git filter-repo --invert-paths --path-glob '*/logs/*' --path-glob '*/tmp/*' --force
git remote add origin <your backup remote>   # filter-repo drops the remote deliberately
git push --force origin main

Then re-clone ~/.remember on every machine that uses it rather than pulling into it.

Doing nothing is a legitimate answer — these are your own session logs in a repository you own. It should just be a decision rather than something nobody told you.

When a push does not go through

A push can fail for two very different reasons, and the backup log tells them apart rather than lumping them together (#253):

The rejection is deliberately not resolved for you. recent.md and archive.md are rewritten wholesale by consolidation rather than appended, so a conflict in them is real and an automatic merge or rebase could corrupt memory silently. The plugin never runs fetch, pull, merge or rebase on your store.

After git_backup.reject_notice_after consecutive rejections (default 3), the next prompt also carries a one-line systemMessage in your terminal, because a stopped backup that only ever appears in a log file is a stopped backup nobody notices — the reporter of #253 lost twelve days of off-machine memory that way. A deferred push never triggers it.

When a commit does not happen

nothing to commit for <slug>, skip used to cover two states as well: the store really had nothing new, or the pathspec matched nothing git tracks. A Windows install ran twelve days on the second while being told the first (#263) — its slug differed from the tracked one by the case of the drive letter, NTFS is case-insensitive so every layer above git was satisfied, and git's pathspecs are case-sensitive so git add matched nothing.

As with a rejected push, the rename is deliberately not done for you, and it also carries a one-line systemMessage on the next prompt — the condition never clears itself, so a log line alone is what let the original go unnoticed.

Restoring on a second machine (off by default)

Backup pushes. It does not pull. If you use the same store from more than one machine, the second machine reads its own stale memory, commits on top of it, and from then on cannot push at all — which is how the divergence above happens in the first place.

git_restore.enabled turns on the other direction. It is off by default and nothing changes until you set it:

// ~/.remember/config.json
{ "git_restore": { "enabled": true } }

With it on, each session start fast-forwards ~/.remember/ from the backup remote before memory is read into context, so the session sees what your other machine wrote.

It only ever fast-forwards. No merge, no rebase, no reset, no checkout, no stash — a test fails if any of those verbs ever appears in the hook. If the store has diverged (commits on both sides) it is refused and reported, for the same reason a rejected push is not auto-resolved: recent.md and archive.md are rewritten wholesale by consolidation, so a conflict there is real and a wrong resolution corrupts memory silently. After git_restore.diverged_notice_after session starts in that state (default 3) the refusal also reaches you as a systemMessage.

No network runs before your first prompt. The git fetch is detached and its result lands on the next session start; the fast-forward itself reads only refs an earlier session already fetched, and is purely local. Measured on the happy path, the whole hook costs ~26 ms on top of process startup — against ~1.7 s for a warm git fetch to GitHub, which is what a synchronous version would have put in front of every prompt. The trade is that a change made on another machine arrives one session later than it could. A restore that lands one session late is still a restore; a session start that hangs waiting on a credential prompt is not.

Because that fetch is unattended, its outcome is recorded and reported: could NOT check the remote is a state of its own and is never rendered as "already up to date". The relevant lines in ~/.remember/<slug>/logs/:

The restore's state files need no .gitignore entry — like the backup's, they live in .git/remember/ rather than beside your memory. That is not only tidiness: git merge --ff-only refuses when an untracked file would be overwritten, so a state file at the store root is a name the restore collides with the day a remote carries it, and the thing that breaks is the fast-forward itself.

Git worktrees

Claude Code sets CLAUDE_PROJECT_DIR to the worktree path for sessions started inside a git worktree. Memory is deliberately not kept in the worktree — it is keyed to the repository's main checkout instead, so that:

• it survives git worktree remove (a worktree-local .remember/ would be deleted with the worktree — silently, since it is gitignored with *), and
• every worktree of the same repo shares one continuous memory rather than a separate throwaway one.

Concretely, REMEMBER_DIR resolves through git's common dir: in legacy mode it lands in <main-checkout>/.remember/, and in external mode the {slug} is computed from the main checkout, so all worktrees map to the same ~/.remember/<slug>/. Only the memory location is redirected — CLAUDE_PROJECT_DIR is left as the worktree path, so session recovery still finds transcripts where Claude Code stored them. Non-worktree checkouts and non-git projects are unaffected.

Running tests

pip install -r requirements-dev.txt
python3 -m pytest

Integration tests (includes shell scripts and prompt validation):

bash scripts/run-tests.sh          # without Haiku
bash scripts/run-tests.sh --live   # with real Haiku call

Skips print their reason

addopts carries -rs, so every skipped test prints why it skipped (#306). That is not verbosity for its own sake. A skip here is a checker saying it could not answer — the shell-parse gate naming the bash 3.2 constructs that went unchecked because no floor interpreter was installed, the timestamp comparison naming the printf '%(...)T' builtin this bash does not have — and rendered as a bare s that sentence never reaches anyone. A green run with silent skips looks exactly like a green run that checked everything.

Read the SKIPPED block at the end of a run before concluding a leg is covered. On a Linux runner it is where you find out that the floor bash was not.

Measuring the warm path (tests/env_cache.py)

scripts/lib-env-cache.sh refuses its cache unless the cache file is -nt every config layer, and bash's -nt compares whole seconds. So a test that writes a config and then counts process spawns on the "warm" run is measuring one of two different things depending on which side of a second boundary the two writes landed on — cold and expensive, or warm and cheap. Both are correct product behaviour; only one is what such a test claims to measure (#303).

Write config layers through tests.env_cache.write_config, which backdates past that granularity, and bracket the run being measured with an EnvCacheProbe:

from tests.env_cache import EnvCacheProbe, write_config

write_config(home / ".remember" / "config.json", {"timezone": "UTC"})
_run(env)                                   # cold — publishes the resolution

probe = EnvCacheProbe(env["TMPDIR"])
probe.snapshot()
_run(env)                                   # the run being measured
probe.assert_warm("the spawn budget")

Backdating alone would only make the number likely to be right. The probe makes the test state which path it measured, with the same three answers everything else here gives: warm, cold, and unknown — the last meaning no resolution was published or replayed, so the number cannot be attributed at all. It needs no clock: a cold run ends in _remember_env_cache_publish, which mvs a temp file over the cache, so the cache file's inode changes; a warm run reads and writes nothing.

tests.env_cache.invalidate is the other direction, for a test that wants the cache refused on purpose — and it needs the same whole-second margin, or the config edit is invisible until the next second.

The Python floor guard

The supported floor is Python 3.9 — the lowest interpreter in the CI matrix (.github/workflows/tests.yml). Syntax newer than the floor does not fail one test, it fails collection, which takes out a whole matrix leg before anything runs, and it is invisible on any machine with a newer Python (which is every machine here).

tests/test_pep604_floor_guard.py catches that statically, on any interpreter, in about a second. It flags PEP 604 unions (str | None) everywhere Python evaluates them:

• parameter, return, and module- or class-level variable annotations, in files without from __future__ import annotations;
• isinstance() / issubclass() arguments — which the future import does not rescue, since those are ordinary runtime expressions;
• the type arguments of cast(), NewType() and TypeVar() (constraints and bound=), which are type positions by those callables' own contract;
• bare assignments at module or class level — Handler = str | None — but only when the discriminator below can tell them from bitwise arithmetic.

It runs in the normal suite; no 3.9 interpreter needs to be installed.

If it fails, the fix is Optional[str] from typing, or adding from __future__ import annotations when the union is only in annotations.

What it does not catch, and why. Handler = str | None and MASK = READ | WRITE are the same AST node, and nothing separates them without type information. The guard flags an assignment only when some operand cannot be bitwise-or'd on any Python — None, a builtin type name, a name imported from typing, or a subscript of one. That is decided by the language, not guessed, so it does not produce false positives on real bitwise code. The price is the other direction: an alias over names it cannot resolve, such as Ids = A | B, is not flagged and will still break a 3.9 leg. That trade is deliberate — a guard people learn to ignore is worse than no guard.

Those cases are not silent. They come back as GuardReport.undecided and are counted in the report's reason: seen, not classified, and not reported as clean. Function-local assignments and the bodies of if TYPE_CHECKING: are out of scope, because neither is evaluated when the module is imported.

Architecture

pipeline/           Python core — extraction, prompts, parsing, types
  extract.py        Session JSONL → filtered exchanges
  haiku.py          Claude CLI wrapper + response parsing
  prompts.py        Template loading and substitution
  consolidate.py    Multi-day compression via Haiku
  log.py            Structured logging
  shell.py          Shell integration — prints eval-able variables
  types.py          Dataclasses for all pipeline data

prompts/            Prompt templates (txt with {{PLACEHOLDER}} substitution)
scripts/            Shell orchestration — locks, cooldowns, file I/O, backgrounding
tests/              pytest suite

Before changing how the nested claude -p call is invoked, or how its output is validated, read docs/nested-model-output.md. That stdout is not guaranteed to be the model speaking, and a validity check that cannot reject an echo of its own prompt is how a hook's refusal ended up in the permanent memory record (#202).

License

Source-available. See LICENSE. Use permitted. Modification, redistribution, and resale prohibited.