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 a stop hook nags when a fact has fallen behind the evidence.

Install

Needs Python 3.8 or later, git, and Claude Code with function hooks enabled. 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. Do not also merge the README’s manual hooks block into settings.json, or wake and recall run twice.

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, PreToolUse on Bash, Stop for the staleness nag) plus the function-hooks module hooks.ts. 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 checks a segmem note command before the shell runs it and denies a note over 280 bytes or with a wrong kind; 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 and never block at stop.

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 Stop hook’s ask.