memory-pulse

# memory-pulse

[![npm](https://img.shields.io/npm/v/memory-pulse)](https://www.npmjs.com/package/memory-pulse)
[![license](https://img.shields.io/badge/license-MIT-6366f1)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-a855f7)](https://github.com/t-crew/memory-pulse)

**Site:** [pulse.strategic-innovations.ai](https://pulse.strategic-innovations.ai/), where the guard runs in the browser. [Compare with Mem0, Zep, Letta and CLAUDE.md](https://pulse.strategic-innovations.ai/compare).

**Corrections that outlive the session.**

Your agent acknowledged the correction, then wrote the old value back next
session. memory-pulse records it once, puts it at the top of every session,
and blocks the edit that reintroduces it, quoting the line that retired it.
For Claude Code, Codex, Cursor, any MCP client and GitHub Actions. The record
is a file in your own repository.

Most memory tools stop at showing the correction to the model. The guard is
the part that acts on it.

All four tool definitions come to **~3.3 KB, about 900 tokens**, and a test in
this repo fails the build if they grow past that. Independent measurements put a typical five to ten server MCP
setup at [50-67k tokens of tool definitions](https://getunblocked.com/blog/mcp-token-budget-autopsy/)
before your first prompt, roughly a third of a 200k context window.

## What it does

A session ends and everything it learned goes with it. memory-pulse keeps a
ledger of **cause → effect** events in a local file, and gives the agent four
tools over it:

| tool | what it does | runs |
|---|---|---|
| `remember` | record a finding (or a **correction**) | locally, offline |
| `pulse` | re-enter the project on a ranked brief, sized to a budget you set | hosted engine |
| `recall` | what caused X? what did X cause? when was the link strongest? | hosted engine |
| `execute` | run JS against memory in a sandbox, where only the return value enters context | hosted engine |

Two design decisions do the heavy lifting.

**Corrections come first, always.** An event recorded with
`kind: "correction"` outranks everything at every brief size and never decays.
The failure this prevents is your agent confidently quoting the benchmark
number you withdrew three sessions ago.

**A weak answer returns nothing.** When recall cannot clear its confidence
floor it returns an empty result, and the brief says so.

## Install

One repo, two plugin hosts, any MCP client. Pick the row for your agent.

**Claude Code, as a plugin.** Skill, MCP tools and the two hooks, from this repo:

```
/plugin marketplace add t-crew/memory-pulse
/plugin install memory-pulse@memory-pulse
```

`claude plugin details memory-pulse` shows what you pay. About 120 tokens are
always on, which is the skill's description. The four tool schemas resolve at
runtime and the hooks are free. The hooks run the plugin's own `server.mjs`,
so what enforces your corrections is the version you installed.

**Codex CLI, as a plugin.** Same files, read from `.codex-plugin/plugin.json`:

```
codex plugin marketplace add t-crew/memory-pulse
codex plugin add memory-pulse@memory-pulse
```

Then, inside Codex, run `/hooks` and trust the two `memory-pulse` entries.
Codex runs no hook it has not shown you, and installing a plugin does not
trust its hooks. That is Codex's rule and a good one.

**Any MCP client, in one line.** Claude Code and Codex are shown, and Cursor
and the rest take the same stdio command:

```
claude mcp add memory-pulse -- npx -y memory-pulse
codex  mcp add memory-pulse -- npx -y memory-pulse
```

**Automatic re-entry without the plugin.** A SessionStart hook runs the brief
before your first prompt and a PreToolUse guard checks edits. Both are
idempotent, both merge into the settings file without clobbering it, and both
stay silent in a project that has no ledger.

```
npx memory-pulse install-hook            # Claude Code: ~/.claude/settings.json
npx memory-pulse install-hook --codex    # Codex:       ~/.codex/hooks.json (then /hooks to trust)
```

Add `--project` to either and the hooks are written into the repo, at
`.claude/settings.json` or `.codex/hooks.json`. Commit that and every clone is
re-entered and guarded with nothing for anyone to install.

A withdrawn number recorded with `kind: "correction"` outranks the history
that contained it, at every brief size and in every session.

**Corrections are enforced, not only surfaced.** Showing an agent a correction
is measurably not enough, because agents re-violate corrections they were just
shown. The PreToolUse guard sees every `Edit` and `Write` in Claude Code and
every `apply_patch` in Codex, where one patch may touch several files and each
is checked under its own path. An edit that writes back a withdrawn value is
**blocked**, and the agent is told which ledger line retired it and when. An
edit that names the replacement beside the old value passes, because "was $49,
now $29" is a comparison. Only a bare reintroduction is blocked. A shell
write is guarded too: a heredoc, a literal redirect or a `tee` has its target
and content read straight out of the command, with nothing executed. A command
whose write cannot be read from the string returns nothing, so it is a miss
rather than a false block, and `check --ci` on the pull request remains the
layer that catches those. Record corrections with the exact
terms:

```
remember({ cause: "pricing-shipped", effect: "price-corrected", kind: "correction",
           note: "measured willingness to pay is $29", withdrawn: ["$49"], replacement: ["$29"] })
```

### Commands

```
npx memory-pulse brief          # the re-entry brief (what the SessionStart hook prints)
npx memory-pulse brief --budget 1500   # size it to the tokens you can spare; the richest tier that fits, corrections first and whole
npx memory-pulse guard          # PreToolUse hook: blocks edits that reintroduce withdrawn terms
                                # (a later correction can `supersedes: [t]` an earlier one — only the latest binds)
npx memory-pulse check --ci     # Memory CI: one of three verdicts for a change, from files you own
npx memory-pulse verify         # row chain + last engine seal; exit 2 if either fails
npx memory-pulse brief --offline  # local render when the engine is unreachable
npx memory-pulse install-hook --ambient  # also record prompts shaped like corrections
npx memory-pulse lint [--ci]    # dry run: do CLAUDE.md / AGENTS.md / .claude/rules still state a value the ledger retired?
npx memory-pulse guard allow "<term>" --path <prefix> "<reason>"   # record a false block as an override
npx memory-pulse report         # correction re-violation scoreboard, computed locally
npx memory-pulse bench          # instant measured metrics on YOUR ledger
npx memory-pulse stats          # your telemetry capsule, signature verified by the engine
npx memory-pulse badge          # README badge markdown from your own signed numbers
npx memory-pulse install-hook   # installs both hooks (idempotent); --codex targets Codex; --project commits them to the repo
```

The plugin also ships a **skill** at `skills/memory-pulse/SKILL.md` that
teaches the agent when to pulse, how to record corrections with withdrawn
terms, and how to respect the guard.

## What the brief tells you before it tells you anything

Every brief opens with one line of provenance, so a session can tell whether
its memory loaded whole, truncated, or not at all:

```
memory-pulse: loaded 852 events from .memory-pulse/events.jsonl · sha256 1a2b3c4d5e6f · 2 binding corrections (10 withdrawn terms) · 1 superseded · ⚠ 1 malformed line skipped: 544 · memory key resumed (+3 new) · tier brief, 5,153 chars
```

Every CORRECTIONS line cites its ledger record as `… -> effect (t12) — note`,
so a correction is evidence the agent can point at. `recall` and the guard name the same `t`.

## Lint: the rules a session loads, checked against the ledger

Governance files drift. A `CLAUDE.md` written in June still says the price is
$49 after the ledger retired it in August, and every new session loads the
stale rule with full confidence. `lint` runs the guard's check over the files
a session will read and gives each of them one of the three verdicts. It
covers `CLAUDE.md`, `AGENTS.md`, `.claude/rules/`, `.cursorrules`,
`.cursor/rules/`, `.github/copilot-instructions.md`, `.codex/AGENTS.md`, and
any paths you pass:

```
$ npx memory-pulse lint
memory-pulse: loaded 2 events from .memory-pulse/events.jsonl · sha256 8e401a39f323 · 1 binding correction (1 withdrawn term)
  BLOCKED     CLAUDE.md
             • "$49" was withdrawn at ledger t2: price-49-launched -> price-corrected-to-29 — use $29
  verified    AGENTS.md
  no evidence .claude/rules/style.md
lint: 3 file(s) — 1 blocked, 1 verified, 1 no evidence — a rule your ledger retired is still being loaded into sessions
```

Exit 2 on any blocked file. Under `--ci` it also exits 1 when it found nothing
to check, so an empty run is never reported as a pass. `--json` is there for
machines. It also names the corrections that carry no `withdrawn` terms, which
surface in the brief but which nothing can enforce.

## Tamper evidence: the ledger cannot be edited quietly

Since 0.3.1 three mechanisms hold, each with its own job:

- **Row chain.** Every row `remember` writes carries `prev`, the previous chained row's hash, and `hash`, the SHA-256 of its own canonical JSON. Rows that existed before the chain are never rewritten, and the first chained row seals them with a digest. An edit in place, a removed row, a reordered row or an unchained row after the chain started all fail `verifyChain()`. A failed chain blocks every `check`, `guard` and `lint` verdict, because a memory whose own history is in question cannot vouch for anything.
- **Set head.** The engine also commits to the ledger as an order-free fold, a multiplicative group mod a 3072-bit prime, which is the MuHash construction Bitcoin Core uses for its UTXO set. Shards from several agents fold to the