memory-pulse MCP server

memory-pulse

Site: pulse.strategic-innovations.ai, where the guard runs in the browser. Compare with Mem0, Zep, Letta and CLAUDE.md. Guide: docs/GUIDE.md, the day-to-day protocol with runnable examples.

Give any agent self-improving memory you can trust in production.

Every correction is kept, put in front of your agent when it matters, and enforced. Memory security is built in: a stored note that reads like an instruction never reaches your agent, every row is hash-chained so any edit to the record shows, and a guard blocks the edit that writes a retired value back.

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.

The four tool definitions come to 3,406 chars, 3.3 KB, about 900 tokens at 3.8 chars per token, measured 2026-09-09. test/client.test.js fails the build past 4,000 chars or 60 tokens either side of 900. Independent measurements put a typical five to ten server MCP setup at 50-67k tokens of tool definitions 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

Every route, host by host, with what runs on each: docs/INSTALL.md (also at pulse.strategic-innovations.ai/install).

Six routes. Pick the row for your agent. Node 18 or newer (package.json engines); the test suite runs on 22 and 24.

remember and help from the shell arrive in 0.5.9. npm served 0.5.8 on 2026-09-09, where both exit 1 with unknown command. If npx serves an older cached release, pin this one: npx -y memory-pulse@0.16.1; from a checkout, run node server.mjs. Four more things in this README are 0.5.9 behaviour and differ on 0.5.8: guard --verbose names non-JSON stdin on stderr (0.5.8 prints nothing), handoff with no transcript writes nothing and says handoff skipped (no transcript) (0.5.8 records a row that reads asked: n/a | files: none), remember reports boundFromEffect when it read the terms out of the effect slug, and a replacement term under 2 characters is dropped like a withdrawn one. 0.5.8's install-hook --codex also says trust the two memory-pulse entries while writing three hooks: trust all three.

One line, any shell. Installs the Claude Code hooks, the Codex hooks when codex is on PATH, and registers the MCP server. It prints its plan first, runs nothing as root, and downloads nothing itself (npx caches the package under ~/.npm). Append -s -- --dry-run after bash to see the commands without running them, or -s -- --project to write the hooks and the Claude Code MCP registration into the current repository. codex mcp add has no project scope; it writes ~/.codex/config.toml on each machine under either flag.

curl -fsSL https://pulse.strategic-innovations.ai/install.sh | bash

Claude Code, as a plugin. Skill, MCP tools and two hooks (SessionStart brief, PreToolUse guard) from this repo, typed inside Claude Code:

/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 (Claude Code, 2026-09-01). 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. The plugin does not carry the PreCompact handoff; to add it, put this entry under hooks.PreCompact in ~/.claude/settings.json:

{ "hooks": [{ "type": "command", "command": "npx -y memory-pulse handoff" }] }

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 three memory-pulse entries (session start, prompt and guard). 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.

npm, global install. install-hook writes four hooks into ~/.claude/settings.json: SessionStart brief, UserPromptSubmit prompt, PreToolUse guard and PreCompact handoff. --codex targets ~/.codex/hooks.json instead, --project writes them into the repository, and --ambient adds the UserPromptSubmit observer.

npm i -g memory-pulse
memory-pulse install-hook

Claude Code or Codex without the plugin. Register the stdio server, then add the hooks:

claude mcp add memory-pulse -- npx -y memory-pulse
codex  mcp add memory-pulse -- npx -y memory-pulse
npx memory-pulse install-hook            # Claude Code: ~/.claude/settings.json
npx memory-pulse install-hook --codex    # Codex:       ~/.codex/hooks.json (then /hooks to trust each entry)
npx memory-pulse install-hook --cursor   # Cursor:      ~/.cursor/hooks.json (brief, fail-closed guard, capture)

claude mcp add without a scope registers the server for the current directory; -s user registers it once for every project. codex mcp add has no scope flag and writes ~/.codex/config.toml (codex-cli 0.153.2, 2026-09-09). Add --project to install-hook 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 Codex clone still trusts the entries once via /hooks, and a scripted codex exec needs that trust in place beforehand.

Cursor. Cursor runs hooks, so npx memory-pulse install-hook --cursor (or --cursor --project for .cursor/hooks.json in the repo) gives Cursor the same brief, guard and capture as Claude Code: the brief at session start, the guard on every write and shell command (fail-closed, so a broken guard blocks rather than passes), and capture with fixes and open threads. For the MCP tools, register command: npx with the args below in .cursor/mcp.json or ~/.cursor/mcp.json. Written from Cursor's hook reference (cursor.com/docs/agent/hooks, read 2026-10-21) and tested against its documented payloads; not yet run inside Cursor itself.

Other stdio clients. The same MCP entry works in any client that speaks MCP over stdio.

{ "mcpServers": { "memory-pulse": { "command": "npx", "args": ["-y", "memory-pulse"], "env": { "MEMORY_PULSE_KEY": "" } } } }

A rule file at .cursor/rules/memory-pulse.mdc tells the agent to call pulse before answering about prior work; the guide has the text.

From source. server.mjs plus the plain modules in lib/, zero dependencies:

git clone https://github.com/t-crew/memory-pulse.git
cd memory-pulse && node server.mjs brief --offline

The second command prints the corrections in this repository's own committed ledger, so you see the output format before installing anything.

What each host runs

Read from server.mjs and hooks/hooks.json, 2026-10-21.

	Claude Code plugin	Codex plugin	install-hook	install-hook --cursor	other MCP clients
four tools	yes	yes	with claude mcp add or codex mcp add	with .cursor/mcp.json	yes
brief at session start	yes	after /hooks trust	yes	yes	no
guard before an edit	Edit|Write|MultiEdit|apply_patch|Bash	apply_patch measured, after trust; Bash is in the matcher, unmeasured in Codex (2026-09-09)	Edit|Write|MultiEdit|Bash (Claude Code), Edit|Write|apply_patch (Codex)	Write|Shell, fail-closed	no; check --ci in CI
capture and consolidation	yes	after /hooks trust, unmeasured in Codex	yes for Claude Code (--no-capture leaves it out); not for --codex	yes	no
handoff before compaction	no	no	yes	no	no
ambient capture	mode agent	no	--ambient or mode agent	no	no
CLI and GitHub Action	everywhere	everywhere	everywhere	everywhere	everywhere

First run

The hooks stay silent in a project that has no ledger: brief prints nothing and exits 0. The first remember creates .memory-pulse/events.jsonl, from a tool call or from the shell:

npx -y memory-pulse@0.16.1 remember pricing-shipped price-corrected --kind correction --withdrawn '$49' --replacement '$29' --note 'measured willingness to pay is $29'
# before 0.6.0 is on npm, the same command from a checkout:
git clone https://github.com/t-crew/memory-pulse.git && node memory-pulse/server.mjs remember pricing-shipped price-corrected --kind correction --withdrawn '$49' --replacement '$29' --note 'measured willingness to pay is $29'

The hook command install-hook writes is npx -y memory-pulse guard, and npx resolves the package on every call: 0.99 s warm and 1.4 s cold (empty npm cache) per edit on an M1 Pro on 2026-10-16 with 0.8.0, against 52 ms for node server.mjs guard on the same ledger, which is the path the plugin runs. If the cost matters, install the plugin, or install globally and edit the hook command to memory-pulse guard.

Where the key goes

export MEMORY_PULSE_KEY=mp_live_... in the shell that starts Claude Code or Codex; the plugins and the hooks read the shell environment. On claude mcp add, pass --env MEMORY_PULSE_KEY=.... In Cursor, the env block above. Do not also run claude mcp add on a plugin install, or you get two servers.

Corrections are enforced, not only surfaced

Showing an agent a correction is not enough. TRACE (arXiv 2606.13174) measured agents re-violating more than half of the corrections they had been shown, with a memory tool installed. The PreToolUse guard sees every Edit, Write and MultiEdit in Claude Code, plus a Bash command whose write is literal in the command string (a heredoc, a redirect or a tee, read with nothing executed), 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 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 catches it.

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"] })

The rules that decide whether the guard can act on a correction:

• Matching is a case-sensitive token. A term cannot start inside another word or number. A number cannot run on into more digits but may carry a unit: $49 blocks $49/mo and not $490. A word under five letters cannot run on (ten does not block tenant); a longer one keeps its inflections. n=14 does not block N=14. Record every spelling you have seen, one term each. before matches case-insensitively, and it advises rather than blocks.
• A replacement anywhere in the edit releases every term of that correction. Make replacements as specific as withdrawn terms: $29, not 29. Terms under 2 characters are dropped and the result says enforceable: false.
• Pass the terms yourself. When a correction declares no withdrawn term and its effect reads X-corrected-to-Y (or -withdrawn-for-, -superseded-by-, -replaced-by-), the terms are read out of the slug: price-corrected-to-29 binds the word price. The result then carries boundFromEffect so you can see it happened.
• A wrong correction is fixed with a new one carrying supersedes: [t]. That retires every term of the earlier row, so re-declare what you keep. guard allow is different: it records an override for one path prefix where the old value is legitimate, and the correction keeps binding elsewhere.
• A note that reads like an instruction is refused, including any angle-bracket tag. Write "the script tag" rather than the tag itself. The check reads a note the way a person sees it: invisible characters, letters borrowed from the Cyrillic or Greek alphabets, fullwidth forms and base64 do not hide an instruction from it (since 0.16.0). A paraphrase or a translation can, because the check is a list of patterns, not a reader.

Test the guard by hand with the payload Claude Code sends before a Write (Edit carries new_string, MultiEdit edits[].new_string, Bash command):

printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"docs/pricing.md","content":"The price is $49."}}' | npx memory-pulse guard; echo "exit $?"

Exit 2 with the ledger line means the guard is live. Stdin that is not hook JSON is allowed through silently; guard --verbose says so on stderr, which is how you tell a miswired hook from "no evidence".

Commands

npx memory-pulse help           # every command and environment variable; also --help, -h
npx memory-pulse serve          # the MCP server on stdio (the default with no command)
npx memory-pulse brief          # the SessionStart re-entry: the organized memory (scaffold) by default; with a key, --engine or --budget the engine brief
npx memory-pulse scaffold       # the organized memory: identity and rules, corrections in force, project state, recent findings, open threads; --section S, --all
npx memory-pulse telemetry show # the opt-in usage counts: exactly what would be sent once a day (on, off, reset)
npx memory-pulse prompt         # UserPromptSubmit hook: the corrections and decisions that bear on the prompt, injected as context
npx memory-pulse brief --budget 2000   # the richest tier that fits 2000 tokens, corrections first and whole
npx memory-pulse brief --offline  # the plain local list; an engine error falls back to the organized memory instead
npx memory-pulse remember <cause> <effect> [--kind correction] [--withdrawn T]... [--replacement T]... [--supersedes N] [--note "..."] [--tags a] [--pinned] [--scope agent]
npx memory-pulse before "<what you are about to do>"   # which corrections bear on the change; exact rung local, learned rung from the engine
npx memory-pulse guard          # PreToolUse hook: blocks edits that reintroduce withdrawn terms (exit 2); --verbose names a non-JSON stdin
npx memory-pulse guard allow "<term>" --path <prefix> "<reason>"   # record a false block as an override
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, this machine's anchor and writer marks; on a break: the first bad row and the command that fixes it; exit 2 if any fails; --strict also fails on unmarked rows; --json for machines
npx memory-pulse append --json '{"cause":"...","effect":"..."}'   # the one way for another tool to write a row: lock, t, prev and hash done here; also `-` for stdin, --scope agent
npx memory-pulse repair --quarantine-tail   # move a tail of rows that fail on their own aside, byte-for-byte, recorded; nothing deleted (also unchained rows this machine did not write)
npx memory-pulse repair --adopt-quarantine <file> --yes   # re-append quarantined rows through the writer after a person has reviewed them
npx memory-pulse seal accept "<why>"   # a stale seal over rows that verify: record the decision, set the old seal aside; refused on a broken chain
npx memory-pulse anchor         # how far this machine's anchor reaches into the ledger, and which rows its writer did not write; --scope agent, --json
npx memory-pulse anchor accept "<why>"   # after a restore, or rows from another machine or an older client: record that you trust the ledger as it stands
npx memory-pulse state          # where this ledger stands: rows, in force, rolled back, heads, seal, branch
npx memory-pulse state export > agent.rain   # the .rain state capsule: rows verbatim, chain head, set head, seal, invariants, one digest
npx memory-pulse state import agent.rain     # on another machine: verify, install byte-identical (or fast-forward), record where it came from
npx memory-pulse state branch exp --at 12 --out exp.rain   # a capsule cut at row 12, named exp; the source ledger is untouched
npx memory-pulse state merge exp.rain        # carry a diverged branch's findings across once; conflicts are named, never resolved quietly
npx memory-pulse state rollback --to 12 "<why>"   # one appended row; rows after 12 stay on record, out of force
npx memory-pulse state verify agent.rain     # verify a capsule without touching any ledger; exit 2 on failure
npx memory-pulse board post --from blue --to science --kind request --title "audit stage 12" --body "..."   # the shared agent message board
npx memory-pulse board read --as science      # unread messages for an agent; also reply, ack, thread, html (the board view), verify
npx memory-pulse board verdict 4 refuted --as coder --defect "..."   # answer a claim; a refutation names its defect; claims lists every claim and its standing
npx memory-pulse board sync on --project <id>   # push the board after every write; the console shows each agent's open asks and every message (board push / status by hand)
npx memory-pulse login          # connect this machine to a hosted project: approve it in the console and the key is saved for you, no copying; turns board sync on
npx memory-pulse logout         # remove the saved key from this machine (revoke it in the console to end it everywhere)
npx memory-pulse capture        # PostToolUse hook (installed by install-hook): one observation per tool call into the session's episode, local, no model
npx memory-pulse consolidate    # Stop / SessionEnd hook: fail-then-pass becomes a fix and still-failing an open thread, each pointing at its evidence
npx memory-pulse weights        # what each memory did: check outcomes shown vs. sat out at random; retired ones marked
npx memory-pulse adopt          # the corrections you already keep (Claude Code feedback memories, CLAUDE.md, AGENTS.md, rules files), shown; --yes enforces them
npx memory-pulse lint [--ci]    # do CLAUDE.md / AGENTS.md / .claude/rules still state a value the ledger retired?
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   # four hooks (idempotent); --codex targets Codex; --project commits them; --ambient adds the observer
npx memory-pulse mode [agent|soul|deliberate]   # show or set the mode
npx memory-pulse identity "<name>, <role>; <stance>"   # pin the agent's self on the agent ledger
npx memory-pulse soul "<persona, voice, values>"   # soul mode: the agent's soul; confirm / reject held changes; history / revert; import / export --openclaw
npx memory-pulse user "<who you are>"   # soul mode: the agent's notes about the person it works with
npx memory-pulse taint          # PreToolUse hook that mode soul installs: marks a session that reads outside content
npx memory-pulse lesson         # the lesson bank the identity block prints, with where each lesson held; --held-out lists what was left out and why
npx memory-pulse lesson probe 41 held --where billing-api   # record that a carried lesson held (or failed) there: the evidence the bank ranks by
npx memory-pulse lesson freeze  # pin the bank you reviewed; every brief prints it until the next freeze or `lesson thaw`
npx memory-pulse handoff        # PreCompact hook: record what the session was doing, from the transcript on stdin
npx memory-pulse ambient        # Stop hook (agent mode): decision, preference, lesson or correction from the last turn
npx memory-pulse observe        # UserPromptSubmit hook: a prompt shaped like a correction is recorded with both terms

Undo: /plugin uninstall memory-pulse inside Claude Code; delete the memory-pulse entries under hooks in ~/.claude/settings.json or ~/.codex/hooks.json; claude mcp remove memory-pulse; delete .memory-pulse/ in a repository; delete ~/.memory-pulse/agent/. Each step leaves the ledgers in place except the last two.

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. The npm tarball ships server.mjs, python/, this file and the licence; the skill, the hooks and the Action live in the repository.