segmem

segmem gives Claude Code a long-term memory that keeps who you are, how this repo works and what happened last week apart, and loads only what the current project needs. It is one Python file and one SQLite database on your machine: no daemon, no server, no API key, no model call. Memory wakes at session start, recall runs on every prompt, and the same prompt hook asks for upkeep when a fact has fallen behind the evidence.

Install

Needs Claude Code 2.1.287 or later, plus Python 3.8 or later and git. The README is written against Claude Code 2.1.261 and declares no minimum version.

claude plugin marketplace add mahuebel/segmem
claude plugin install segmem@segmem

The README writes them as in-session /plugin commands. Start a new session: the first wake prints an empty header and Claude fills it in with segmem note as you work. Skip the README’s manual hooks block: since 0.13.1 it claims each session with --once too, so it no longer doubles wake and recall, but it still starts a second process per event.

How it works

Kinds and scopes. Every fact has a kind and a scope. identity (how you like to work) and people default to global; procedural (how this repo works) and episodic (decisions and root causes) default to the current project, keyed by the git main repo path so worktrees share it. At wake, identity and procedural facts load whole, people load as names only, and episodic history loads through a decaying window of 16 lines per project and 8 global: the newest verbatim, older ones as one-line summaries Claude writes with segmem nap. A project fact overrides a global one on the same tag, with both shown. Promotion to global needs the same statement in three projects.

Two paths, one voice. The plugin ships classic command hooks in hooks.json (SessionStart for the doctrine block and wake, UserPromptSubmit for recall and the upkeep ask, PreToolUse on Bash) plus the function-hooks module hooks.ts. Until 0.12 a Stop hook did the nagging; version 0.13.0 (30 September 2026) dropped it, because a block after the answer scrolled the answer away. The prompt hook now asks in a <segmem-upkeep> block, one subject per prompt and each once per session, before the work and without mentioning it in the answer. With the flag on, both run and every output call passes --once: the first path to insert a row in the claims table serves that session, so nothing prints twice. The author measured that the command hook wins the wake race every time, so the module’s segmem context block at prompt.context usually stays empty. Without the flag you lose only what follows.

What the module adds. At prompt.context it runs segmem stale --count and pins segmem: N under pressure beneath the prompt, and it toasts contradictions such as segmem: #12 overrides #7 for eight seconds. At agent.spawn it appends the read-only rule (wake and recall, never note) to every subagent prompt, and never refuses a spawn. At tool.call on Bash it runs a segmem note command through segmem check-note before the shell runs it and denies a note over 280 bytes or with a wrong kind, with a hint for a near-miss tag; every other command passes. At session.start it registers a recall tool, called as mcp__segmem__recall, that runs segmem recall.

What it reads. The text of every prompt, whatever its origin, goes on stdin to segmem hook, which pulls out identifiers (code spans, #123, paths, snake and kebab names, capitalized words that are known tags) and searches the project plus global memory. Every Bash command goes to segmem hook --tool, which prints facts tagged with the program about to run, once per session. What a prompt leaves behind is a touch: which entity was mentioned, from which project.

What it stores. One file, ~/.segmem/segmem.db, in WAL mode (SEGMEM_DIR moves it): append-only facts, an FTS5 index, the episodic summary tree and the touch telemetry. Facts are never edited, only superseded or forgotten by id. Nothing leaves the machine: the module makes process, session, tool and UI calls only, and segmem serve is a loopback page you start by hand.

What it costs. Wake is a fixed-budget block plus the doctrine block at start; recall adds at most eight hits in a <segmem-recall> block and stays silent when a prompt has no identifiers or no hits. The author gives no token figure; the overview tab of segmem serve reports each scope’s wake cost. SEGMEM_QUIET=1 makes an unattended session recall without recording touches or asking for upkeep.

Limitations

• A compaction wakes through the command hook only: prompt.context does not fire again after it.
• The status line and the toast have nowhere to draw in a headless run.
• segmem runs as an executable script, ${CLAUDE_PLUGIN_ROOT}/segmem; the author says nothing about Windows.
• Summaries come from Claude on request. The plugin never runs nap itself, so a compression backlog waits for the prompt hook’s ask, once per session.