Stashpad

Stashpad Good work. Worth remembering. Project website · Get started · Connect your agent · Contribute

Local memory for any AI coding agent: an MCP server and CLI that keep plain Markdown notes with sources, a review queue and search.

Works with Claude Code, Codex, Cursor, VS Code, Gemini CLI and any other MCP client, or with no MCP at all (plain commands and an AGENTS.md block). No model, no cloud, no dependencies: Node 20 or newer.

Quickstart

npm install -g stashpad

stashpad setup # prints the MCP settings for your agent app (generic, claude-code, vscode, codex) stashpad doctor --client # starts the server the way your agent app does and checks it answers

Expected: client start: the server answered with 8 tools in ... ms and Nothing is broken.

Claude Code users can install the plugin instead, which also adds the hooks below: /plugin marketplace add laaielichter/stashpad, then /plugin install stashpad@stashpad (or stashpad@reverseport from the ReversePort marketplace).

Why Stashpad?

• Your agent stops forgetting after compaction. Pinned rules and the latest handoff come back at the start of every session and right after /compact.
• Rules you set stay in front of the agent. stashpad pin keeps the few rules that matter in every brief; each prompt gets only the memories that clearly match it, once per session.
• Memory that knows when the code moved on. Anchor a memory to its files and recall says "changed since saved", follows a renamed file and skips a memory whose files are gone. Decisions keep why they were made and what lost (stashpad decide).
• Nothing ends up in memory behind your back. Agent, tool and web notes wait for a person; near-copies, secrets and hidden text are refused.
• You can read, fix and keep it. Memories are Markdown files with a source and dates, in your project, in git if you want. Old facts are ended, never overwritten.
• You see what the agent got. stashpad shown lists which memories were put in front of the agent and how many characters, and a status line keeps the review queue in view.
• It keeps working. One store per project (worktrees share it), a lock for parallel writers, snapshots before changes, doctor that says what to fix.

How it compares

What Stashpad does not do: semantic search (word search finds about 2 of 3 reworded questions in our eval), automatic extraction of memories from chats (by design), sync between computers (use git), or a shared server for a team.

Start and end of a session

stashpad brief                  # short summary: pinned rules, newest memories, open handoff

stashpad recall "add a postgres migration" # the few memories that clearly match a request stashpad decide "We use Postgres" --why "several workers write at once" --rejected SQLite # a decision with its reason stashpad handoff leave --text "Half done: auth. Next: tests." # a note the next session reads once stashpad sync-agents AGENTS.md # put the brief in a file agents already read (no MCP needed)

With the Claude Code plugin these run as hooks: at session start and after compaction, on each prompt (each memory once per session), and before compaction and at session end (an automatic handoff with the branch and uncommitted files; a session that crashed is noticed at the next start). Pause them per project with stashpad hooks off; add stashpad setup claude-code --status-line for a status bar line. See docs/HOOKS.md. Agents: read AGENT-GUIDE.md.

Develop

Requires Node 20 or newer. No other dependencies.

npm test                 # run the tests

npm run build # build dist/ node bin/stashpad.mjs --help

Memories live in .stashpad/memories of the project: the nearest folder above that has one, else the git root, so subfolders and git worktrees share one store. stashpad where shows which store a folder uses and why. Set STASHPAD_DIR or pass --dir to choose yourself. What is true in every project (your language, your commit style) goes in the global store: add --global (or -g).

Use it

stashpad save db-choice --kind decision --source-type user --source-ref "statement in chat" --text "We keep data in SQLite."

stashpad search "sqlite" --json stashpad save db-choice-v2 --kind decision --source-type user --source-ref "later statement" --text "We keep data in Postgres." --supersedes db-choice stashpad history db-choice-v2 stashpad search database --kind decision --as-of 2026-03-01 --explain # what was decided on that day, and why it matched stashpad entities # names, tools and files the memories talk about stashpad about Postgres # every memory about it, and what is mentioned with it stashpad confirm db-choice-v2 # still true; doctor flags agent memories nobody confirmed for 180 days stashpad anchor tax-rules src/billing/tax.ts # recall and lint say when that file changes; confirm re-anchors stashpad anchors --changed # anchored memories whose files changed, moved or are gone stashpad shown # what was put in front of the agent: memory ids and sizes, never text stashpad handoff leave --text "Half done: auth. Next: tests." # a note the next session reads once stashpad handoff claim # take it (a person's notes first); listing never takes one stashpad feedback db-choice --signal stale # helpful, stale or wrong; wrong also asks for it to end stashpad feedback --last --signal wrong # about the memory the prompt hook gave last stashpad lint # what deserves a look; changes nothing

The command line, the MCP server and the review page can run at the same time: every write takes a short lock on the store.

Writes from agents, tools and the web wait in review:

stashpad review

stashpad accept stashpad reject --reason "not verified" stashpad audit

Use it from an MCP client

stashpad setup prints the right block for your client, with the full path to Node (a bare node is the most common reason a server does not connect). It looks like this:

{

"mcpServers": { "stashpad": { "command": "/full/path/to/node", "args": ["/full/path/to/stashpad/bin/stashpad.mjs", "mcp"] } } }

Eight tools: stashpad_search, stashpad_get, stashpad_recent, stashpad_about, stashpad_save, stashpad_forget, stashpad_handoff, stashpad_feedback. stashpad_save takes optional files (read when a person accepts) and, for decisions, why and rejected.

Check it, import into it

stashpad eval                          # 40 notes, 33 queries (English and Dutch), safety checks; no language model is called. Paraphrased questions are measured too (about 2 of 3 found): word search misses some rewordings, and that is reported openly.

stashpad import notes.jsonl # queue memories from an export; they wait for review stashpad export --out memories.jsonl # back up current memories as JSON Lines (--all adds ended ones) stashpad save --kind fact --source-type user --source-file notes.txt --text "..." # keeps a copy of the raw source

stashpad review also shows when a waiting memory may conflict with a current one, and whether accepting it would end that one.

Review in a page

stashpad ui            # opens http://127.0.0.1:4317/ to review, search and read the audit log

stashpad ui --open # the same, and opens the page in your browser

Only this computer can reach the page. It is a small local page with no outside resources. See the decision.

Imports come in as JSON Lines (id, kind, text, optional valid_from, source_ref) or as plain text, one fact per paragraph.

Principles

• Plain files first. The files are the source of truth.
• Nothing from an agent, tool or web page is stored until a person accepts it.
• Secrets are refused at write time: provider keys and tokens (OpenAI, Anthropic, GitHub, GitLab, AWS, Google, Stripe, Slack, npm, Hugging Face, SendGrid and more), JWTs, Bearer tokens, passwords in connection strings, on command lines and in sentences, and the values of this computer's own secret-named environment variables and .env files (compared in memory, never stored). The automatic handoff masks a secret as [REDACTED] instead of dropping the request.
• Invisible characters are refused, and look-alike or split-up words cannot hide an instruction or a secret.
• Instruction-like text (English and Dutch) is flagged for the reviewer.
• A gatekeeper refuses agent notes that are too short or near-copies of an existing or waiting memory, and logs the refusal in the audit log. Notes a person writes are never blocked.
• Limits: 4000 characters per memory, 200 writes waiting for review.
• Recalled text is labelled as data, not instructions, and comes inside one block; tags that could pass for the agent app's own text ( , , …) are defused.
• Paths a memory is anchored to sta