Your saved research, in every answer.
the stashwise command, published as @stashwiseapp/mcp
Stashwise is a personal knowledge base: you save articles, videos, threads and posts, and it turns them into an AI organized library and wiki. This package connects that library to Claude Code, Cursor, Codex and Claude Desktop, so the things you saved months ago show up in the answer you need today.
You ask an ordinary question. You do not mention Stashwise, and you do not remember saving anything about it.
❯ is there an open source alternative to ahrefs
Stashwise · 1 related save: Ahrefs
⏺ Your library already has the answer's centerpiece. Let me verify
its current state and see what else exists.
⎿ search_stashwise("open source SEO tool alternative")
⎿ get_stashwise_context(kind="content", result_id="...")
⎿ Web Search("OpenSEO github bensenescu self-hosted")
You saved OpenSEO in July: an open source, self hosted SEO tool
built as an alternative to Semrush and Ahrefs, with agent
integration for keyword research and competitor analysis.
→ x.com/bensenescu/status/2078737738493301060Four things happened there, and only the first is automatic:
- The hook noticed. Every prompt you submit is checked against your library. This one matched a save, so you got the one line notice naming it.
- The agent disagreed with the match. It got
Ahrefs, judged that the commercial tool was not what you were asking for, and searched your library again with a better query of its own. - It hydrated the result. Search snippets identify candidates; the context call returned the saved item's full body, takeaways, notes, links, and wiki connections before the agent used it as evidence.
- It answered from the full material, with the source link, and used current web research only as a supplement.
That second step is the point. The automatic check only sees your raw prompt, so it guesses before anyone has worked out what you are really asking. The agent can then go back with a sharper query.
Codex, Cursor, and Claude can connect directly to the hosted Stashwise MCP endpoint:
https://stashwise-api.fly.dev/mcp/
The hosted connection uses OAuth. Installing the Codex plugin—or adding the URL as a remote MCP connector in Cursor or Claude—opens Stashwise in the browser for approval. It does not require Node, npx, an API token, or OS-keychain setup. See integrations/ for the client-specific assets.
Install the Codex plugin on macOS or Linux with one command:
curl -fsSL https://raw.githubusercontent.com/StashwiseAI/stashwise-cli/main/scripts/install-codex-plugin.sh | shThe installer uses Codex's native marketplace and plugin commands, can be rerun for updates, and migrates the earlier stashwise@personal beta installation. Windows and manual installation commands are in the integration guide.
The Codex plugin also teaches Codex when to consult saved research, how to refine an incomplete match, and when writes are appropriate. Search stays lightweight, then get_stashwise_context hydrates each result the answer actually uses: library results include the full item and its wiki links; wiki results include the synthesized page, linked source items and takeaways, claims, contradictions, and related entities. With explicit user intent, it can also save URLs and research notes, create nested folders, and move items. Deletion, folder rename/reparent, and account management are intentionally unavailable.
On local Codex surfaces, the plugin bundles an ambient UserPromptSubmit hook that reminds Codex to check Stashwise when saved research could materially improve an answer. The hook never reads credentials, sends the prompt over the network, or performs writes; searches still go through the OAuth-protected MCP tools. After installing or updating the plugin, open /hooks, review and trust the Stashwise hook, then start a new task. If the hook is disabled or untrusted, explicit Stashwise requests still work through the plugin skill and MCP server. Codex Cloud does not run the local lifecycle hook, so it uses that skill-based behavior instead.
npm i -g @stashwiseapp/mcp
stashwise authauth opens stashwise.co/cli, you click Authorize, and a token lands in your OS keychain (macOS Keychain, Windows Credential Vault, Linux libsecret). On a headless box it also prints a URL and an 8 character code you can enter by hand.
Then wire it into your agent. Claude Code gets both surfaces:
claude mcp add -s user stashwise -- stashwise # the search tool
stashwise hook install # the automatic checkingCursor, Codex, Claude Desktop, and running without a global install
The direct pre-search hook installed by stashwise hook install is Claude Code only. The Codex plugin has its own ambient lifecycle hook; Cursor and other MCP hosts get the Stashwise tools without a prompt hook.
Cursor · ▸ Add to Cursor or add it to ~/.cursor/mcp.json:
{
"mcpServers": {
"stashwise": { "command": "stashwise" }
}
}Codex CLI
codex mcp add stashwise -- stashwise…or in ~/.codex/config.toml:
[mcp_servers.stashwise]
command = "stashwise"Claude Desktop · edit the config, then restart the app:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"stashwise": { "command": "stashwise" }
}
}Prefer not to install globally? Every command works through npx, and every config above accepts it in place of "command": "stashwise":
npx -y --package @stashwiseapp/mcp@latest stashwise auth{
"command": "npx",
"args": ["-y", "--package", "@stashwiseapp/mcp@latest", "stashwise"]
}No Stashwise account yet? Create one and save a few things first. Search only ever returns your own library.
Pull starts with search_stashwise. The agent calls it when it decides your library is relevant, or when you ask directly, then calls get_stashwise_context for the result or results it will rely on. This two-step retrieval keeps discovery fast without forcing answers to rely on truncated summaries. It works in every MCP host.
Push is host-specific. Claude Code's CLI hook searches each eligible prompt before the agent sees it and surfaces strong matches without anyone asking. The local Codex plugin hook injects relevance guidance before the turn, then Codex uses its existing OAuth MCP connection when a search is warranted. Codex Cloud and hosts without lifecycle hooks rely on the plugin skill or their own agent instructions.
Push is what makes the library ambient rather than something you have to remember to consult. It reaches you on two separate channels, deliberately:
| Channel | Goes to | Why |
|---|---|---|
systemMessage |
you | The harness always displays it, so you learn what you saved even if the answer never mentions it |
additionalContext |
the agent | So it can quote and cite the material inline |
Earlier versions put both in one channel and depended on the model to relay what it found. It often did not, particularly when a loaded skill dominated the answer.
The Claude Code pre-search hook runs on every eligible prompt you type, so this matters more than it would for an ordinary CLI. The Codex ambient hook makes no network request itself and adds only a short developer-context instruction.
| Added latency | ~180 ms per prompt, warm. Measured 177 / 183 / 222 ms against production; roughly 130 to 170 ms of that is the search itself |
| Hard timeout | 2500 ms, then it gives up silently. Tunable |
| Free prompts | Anything under 15 characters, or starting with /, ! or #, exits before any network call. Slash commands and shell lines cost nothing |
| On failure | Missing token, unreachable backend, timeout, malformed input: all exit quietly. Your prompt is never blocked, altered or delayed beyond the timeout |
| What leaves your machine | The prompt text, capped at 2000 characters, sent to your own account's backend. Nothing else |
| How noisy | At most 3 suggestions, and each item is offered at most once per session |
Set STASHWISE_HOOK_DEBUG=1 to see on stderr why a given prompt stayed silent.
Most prompts produce nothing, by design. A suggestion has to be worth interrupting you for.
The test is not a fixed score. It is whether one result stands out from the rest. That distinction matters because similarity scores are not comparable between questions: a broad prompt like "how should I structure skills for an AI agent" lands near the middle of a whole topic cluster and scores respectably against a dozen mediocre matches, while a narrow one like "SKILL.md frontmatter" lands somewhere sparse and scores poorly against the single item that genuinely answers it. Any fixed threshold is therefore too low for the first and too high for the second.
So the hook looks at the shape of the results instead. A flat pack of similar scores means nothing stood out, and it stays silent no matter how high those scores are. A clear leader opens the gate.
On top of that:
- Wiki entities are held to a higher bar than things you saved. They are derived abstractions with no link to open, and they match incidental mentions: a generic
TypeScriptpage will match any type error you ever paste. - Anything without a real summary is dropped rather than shown as a bare title.
- Nothing repeats within a session.
Commands
| Command | What it does |
|---|---|
stashwise |
Start the stdio MCP server. This is what agent hosts spawn; you rarely run it yourself |
stashwise auth |
Pair this machine with your account. Run once |
stashwise search "..." |
Search from the terminal, no agent involved |
stashwise doctor |
Check config, token validity and backend reachability. Run this first when something is off |
stashwise hook install |
Register the prompt hook in ~/.claude/settings.json |
stashwise hook uninstall |
Remove it |
stashwise --version |
Print the installed version |
stashwise --help |
Full usage |
hook install registers at the user level, so it applies to every project on the machine. It pins the command to the version you installed, so npx serves it from cache rather than hitting the registry on every prompt. Rerun it after upgrading to move the pin.
$ stashwise search "what did I save about HNSW indexes"
Results for "what did I save about HNSW indexes" (scope: all)
1. Approximate Nearest Neighbors with HNSW · youtube · score 0.83
A walkthrough of hierarchical navigable small world graphs and how the …
https://youtube.com/watch?v=…
2. pgvector HNSW tuning notes · github · score 0.79
ef_search vs ef_construction trade-offs when indexing embeddings …
https://github.com/…
2 results · 138mssearch flag |
Values | Default | Meaning |
|---|---|---|---|
--scope |
library · wiki · all |
all |
Saved items, extracted wiki entities, or both |
--k |
1 to 25 |
8 |
Max results |
The Stashwise MCP tools
Your agent gets retrieval tools plus folder organization tools. list_stashwise_categories returns full hierarchy paths; create_stashwise_folder creates one node at a time; and move_stashwise_items moves up to 100 items atomically (use a null category for Unsorted). Writes require explicit user intent.
| Param | Type | Default | Notes |
|---|---|---|---|
query |
string (required) | none | Natural language search query |
k |
integer 1 to 25 | 8 |
Max results |
scope |
library · wiki · all |
all |
What to search |
Returns ranked snippets with citations:
{
"query": "HNSW indexes",
"retrieval_ms": 138,
"results": [
{
"kind": "content",
"id": "…",
"title": "Approximate Nearest Neighbors with HNSW",
"snippet": "A walkthrough of hierarchical navigable small world graphs…",
"source_url": "https://youtube.com/watch?v=…",
"source_platform": "youtube",
"score": 0.83,
"citation": "Approximate Nearest Neighbors with HNSW — youtube",
"saved_at": "2026-05-02T11:20:00Z"
}
]
}kind is content for something you saved and entity for a concept the wiki extracted across several saves. Maps to POST /api/v1/agent/search.
Tuning the hook
Edit the command in ~/.claude/settings.json:
stashwise hook --min-score 0.5 --k 10 --timeout-ms 4000
| Flag | Range | Default | Meaning |
|---|---|---|---|
--min-score |
0 to 1 | 0.45 |
Score a result must clear to fill a slot. Note this decides which results qualify, not whether any are shown (that is the shape gate above) |
--k |
1 to 25 | 6 |
Results fetched per prompt |
--timeout-ms |
100 to 60000 | 2500 |
How long to wait before staying silent |
Unknown flags are ignored, so a settings file written by a newer version never breaks an older binary.
Environment variables
| Variable | Default | Purpose |
|---|---|---|
STASHWISE_API_URL |
https://stashwise-api.fly.dev/api/v1 |
Backend base URL |
STASHWISE_WEB_URL |
https://stashwise.co |
Webapp base URL, used by auth |
STASHWISE_HOOK_DEBUG |
unset | Set to 1 to log hook decisions to stderr |
Pointing at a local backend during development:
STASHWISE_API_URL=http://127.0.0.1:8000/api/v1 stashwise search "test"Troubleshooting
- "Stashwise is not authenticated." Run
stashwise auth. If searches worked before and suddenly stopped, the token may have been revoked from your account page; rerunauth. - The agent does not see the tool. Restart the host after editing its config, Claude Desktop especially. In Claude Code run
/mcpto confirmstashwiseis connected. OS keychain unavailable …Expected on headless or CI Linux without libsecret. The token falls back to~/.stashwise/credentials.jsonat mode0600and everything still works.- The hook went quiet after an upgrade. Rerun
stashwise hook installto move the version pin. A pin naming a version that has aged out of the npx cache resolves slowly or not at all, and because the hook fails silently by design, a dead pin looks exactly like "no matches found". - Upgrading from 0.3.0 or earlier. The binary was named
mcpand is nowstashwise. Existing hook pins are still recognized, sohook installmigrates yours in place andhook uninstallstill finds it. Nothing to do by hand. - Still stuck?
stashwise doctorreports config, token validity and backend reachability in one shot.
Managing paired machines
Every machine you have authorized is listed under Account → Connect AI agents at stashwise.co, where you can revoke any of them. Newly paired agents can search your library and, only when you explicitly ask, create folders or move items. They cannot delete content or manage your account. Older read-only pairings stay read-only until you rerun stashwise auth.
MIT