search_notesLABSCO SUMMARY
The decisions survive the session, and the tool you used to make them.
Two things lift it above a notes folder: search knows when a note has gone stale because its source changed, and the handoff is a first-class object — so the next session starts from what was decided rather than from an empty window.
What it is
A single binary that indexes your markdown notes, surfaces the relevant ones at session start, and records decisions and handoffs so the next session picks up where the last one stopped. It works across Claude Code, Cursor, Windsurf, Codex CLI and Gemini CLI, entirely on your machine — no cloud, no telemetry.
What you get
- 19 MCP tools covering search, reading, writing and vault health
- Search —
search_notessemantically,search_notes_filteredby domain, tag or agent,search_across_vaultsfederated across several,find_similar_notes - Reading —
get_noteby path,get_session_contextfor pinned notes plus the latest handoff and git state,recent_activity - Writing —
save_note,save_decisionfor a structured project decision,create_handofffor a session handoff,save_kaizenfor improvement items with provenance - Memory hygiene —
mem_consolidatemerges related notes,mem_briefgenerates an orientation briefing,mem_healthreports trust across the vault,mem_forgetsuppresses a note from search withmem_restoreandmem_list_suppressedto undo and audit it - Index management —
reindexandindex_stats - Memory integrity: provenance is tracked, changed source files are detected, and stale notes rank lower in search automatically
- 17 pre-built knowledge vaults with 870+ curated notes, installed with one command
Requirements
Install with the shell script, PowerShell, or npm install -g @sgx-labs/same; it runs on Mac, Linux, Windows and Raspberry Pi. Then same init in your project sets up the hooks and MCP tools. It works with no external services at all — keyword search when no embedding model is available — and same web --mcp exposes an HTTP MCP endpoint with Bearer token auth for clients that cannot spawn a process. Privacy is structural rather than advisory: _PRIVATE/ is never indexed and research/ is indexed but never committed. Push protection and PII scanning are opt-in, turned on with same guard settings set push-protect on. Licensed BSL 1.1.
Setup effort
One command — curl -fsSL https://statelessagent.com/install.sh | bash
USE CASES
01
Picking up where yesterday stopped
Session context returns the pinned notes, the latest handoff and the git state together, so the agent starts oriented.
02
Recording why you chose one approach
Save it as a structured decision rather than a paragraph in a chat log nobody will find again.
03
Finding the answer buried in an unrelated note
Semantic search across the vault, narrowed by domain or tag when the store gets large.
04
Trusting what the store tells you
Check vault health to see which notes have drifted from their source, and let stale ones rank lower rather than deleting them.
05
Getting domain knowledge fast
Install a pre-built vault so the agent has curated notes on the subject before you have written any.
06
Suppressing a note that keeps surfacing wrongly
Forget it from search results, list what is suppressed, and restore it if the call was wrong.
19 tools
Listed in project docs. Your client may show a different list.
search_notes_filteredsearch_across_vaultsget_notefind_similar_notesget_session_contextrecent_activitysave_notesave_decisioncreate_handoffsave_kaizenreindexindex_statsmem_consolidatemem_briefmem_healthmem_forgetmem_restoremem_list_suppressedBEFORE YOU INSTALL
What to know first
Tools you get
19 tools named in the project's documentation.
INSTALLATION
Connect your client
Server setup
TERMINAL
curl -fsSL https://statelessagent.com/install.sh | bashMCP Clients
Claude Code
CLAUDE CODE · TERMINAL
same initCursor, Windsurf, Gemini CLI
JSON
{
"mcpServers": {
"same": {
"command": "npx",
"args": [
"-y",
"@sgx-labs/same",
"mcp",
"--vault",
"<YOUR_PATH_TO_NOTES>"
]
}
}
}Open WebUI, LobeChat
TERMINAL
same web --mcp --fgAdd http://127.0.0.1:4078/mcp to the client as a streamable HTTP MCP server, with the header Authorization: Bearer followed by the token the command prints
Run it from your notes folder, after same init. The printed token lasts for this session only; set SAME_MCP_TOKEN (or auth.token in the config) for one that persists. --port changes 4078.
Docker
DOCKER · TERMINAL
git clone --depth 1 https://github.com/sgx-labs/statelessagent.git
cd statelessagent && docker build -t same .
docker run --rm -i -v ~/my-notes:/vault same mcpThe same image is built on your machine, not pulled from a registry. ~/my-notes, the part of the -v value before the colon, is a sample; yours is your notes folder.
