SAME - Stateless Agent Memory Engine MCP Server

<!-- mcp-name: io.github.sgx-labs/same -->

SAME — Persistent Memory for AI Coding Agents

Your AI forgets everything between sessions. SAME fixes that.

SAME gives every AI coding tool persistent memory. Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI — one memory layer that works everywhere. It indexes your markdown notes, surfaces relevant context automatically, and records decisions and handoffs so your AI picks up where it left off.

One binary. Fully local. No cloud. No telemetry. Mac, Linux, Windows, Raspberry Pi.

Install

# macOS / Linux
curl -fsSL https://statelessagent.com/install.sh | bash

# Windows (PowerShell)
irm https://statelessagent.com/install.ps1 | iex

Or via npm (all platforms): npm install -g @sgx-labs/same

Installed via npm? Update with npx same@latest or npm update -g @sgx-labs/same.

See It Work

same demo

Indexing 5 sample notes...
Searching: "authentication decision"

  1. decisions/auth-strategy.md (score: 0.94)
     "We chose JWT with refresh tokens for..."

  2. notes/api-security.md (score: 0.87)
     "Auth middleware validates tokens at..."

Asking: "what did we decide about authentication?"

  Based on your notes, you decided to use JWT with refresh
  tokens (decisions/auth-strategy.md). The API middleware
  validates tokens at the gateway level (notes/api-security.md).

No accounts. No API keys. Everything runs locally.

Quickstart

# 1. Point SAME at your project
cd ~/my-project && same init

# 2. Test search
same search "authentication decision"

# 3. Done. Your AI now has memory.
# Start Claude Code, Cursor, or any MCP client.

same init sets up hooks and MCP tools automatically. Your AI gets relevant context on every session start.

Key Features

• Your AI remembers everything -- Decisions, handoffs, and context survive across sessions. Close your terminal, switch projects, come back tomorrow. Nothing gets lost.

• Memory integrity -- Tracks provenance (where notes came from), detects when source files change, and flags stale knowledge. Stale notes rank lower in search automatically. same health shows trust state across your vault.

• Dual-layer memory -- Extracts atomic facts from your notes via LLM. Facts are independently searchable and boost source notes in search results. The right answer surfaces even when the fact is buried in an unrelated conversation.

• Streamable HTTP transport -- same web --mcp enables an HTTP MCP endpoint with Bearer token auth. Connect from Open WebUI, LobeChat, or any HTTP MCP client — no stdio required.

• Works with your tools -- 19 MCP tools for Claude Code, Cursor, Windsurf, or any MCP client. Search, save decisions, create handoffs without leaving your editor.

• Safe for teams -- Multiple AI agents on the same codebase won't step on each other. File claims, push protection, and attribution built in.

• Instant expertise -- 17 pre-built knowledge vaults with 870+ curated notes. One command to install. Your AI gets domain knowledge in seconds.

• Connected knowledge -- See how decisions, files, and notes relate to each other. Ask "what depends on this?" and get real answers. Powered by SQLite.

Security & Teams

SAME includes built-in PII scanning and push protection:

• PII scanning -- Pre-commit hooks detect emails, API keys, secrets, and personal data before they reach git. Configurable blocklists with false-positive review workflow.
• Push protection -- Multi-agent file claims prevent AI agents from overwriting each other's work. Advisory locks with attribution.
• Audit logging -- Every guard scan, every allow decision, every override is logged.
• Privacy tiers -- _PRIVATE/ is never indexed. research/ is indexed but never committed. Your notes, your rules.

same guard settings set push-protect on    # enable push protection
same guard scan                            # run PII scan manually

How It Works

Your Notes (.md)  -->  Embeddings  -->  SQLite  -->  Your AI Tool
                       (local or        (search      (Claude Code,
                        cloud)           + rank)      Cursor, etc.)

Your markdown notes get embedded and stored in SQLite. When your AI starts a session, SAME surfaces relevant context via hooks or MCP. Decisions get extracted. Handoffs get generated. The next session picks up where the last one stopped.

No Ollama? No problem. SAME runs with zero external dependencies using keyword search (SQLite FTS5). Add Ollama later for semantic search -- same reindex upgrades instantly.

Why SAME

Without SAME	With SAME
Re-explain everything each session	AI picks up where you left off
"Didn't we decide to use JWT?"	Decision surfaces automatically
"Is this note still accurate?"	Trust state flags stale knowledge
Close terminal = context lost	Handoff recovers the session
Copy-paste notes into chat	same ask with source citations
Context compacted mid-task	Pinned notes survive compaction

The Numbers

Metric	Value
Recall@5	100% keyword, 84% semantic on internal eval (68 cases). Held-out: 90% Recall@5 on 30 blind cases (see eval/METHODOLOGY.md)
MRR	0.65 keyword, 0.62 semantic
Prompt overhead	<200ms
Binary size	~14MB
Setup time	Under 2 minutes

Add to Your AI Tool

Claude Code (recommended)

same init    # installs 6 hooks + MCP automatically

Cursor / Windsurf / Any MCP Client

Add to your MCP config (.mcp.json, Cursor settings, etc.):

{
  "mcpServers": {
    "same": {
      "command": "npx",
      "args": ["-y", "@sgx-labs/same", "mcp", "--vault", "/path/to/your/notes"]
    }
  }
}

19 MCP tools available instantly. Works without Ollama (keyword fallback).

Switch between Claude Code and Cursor without losing context. Your memory travels with you.

Tool Compatibility

Claude Code gets full automatic handoffs via hooks. Cursor, Windsurf, Codex CLI, Gemini CLI get full MCP tool access (search, save, decisions, graph) but handoffs need to be triggered manually. We're working on automatic handoff support for more editors.

MCP Server

Tool	What it does
search_notes	Semantic search across your knowledge base
search_notes_filtered	Search with domain/tag/agent filters
search_across_vaults	Federated search across multiple vaults
get_note	Read full note content by path
find_similar_notes	Discover related notes
get_session_context	Pinned notes + latest handoff + git state
recent_activity	Recently modified notes
save_note	Create or update a note
save_decision	Log a structured project decision
create_handoff	Write a session handoff
reindex	Re-scan and re-index the vault
index_stats	Index health and statistics
mem_consolidate	Consolidate related notes via LLM
mem_brief	Generate orientation briefing
mem_health	Vault health with trust analysis
mem_forget	Suppress a note from search results
mem_restore	Undo mem_forget (unsuppress a note)
mem_list_suppressed	List suppressed notes
save_kaizen	Log improvement items with provenance

SeedVaults

Pre-built knowledge vaults. One command to install.

same seed list                              # browse available seeds
same seed install claude-code-power-user    # install one

Seed	Notes	What you get
same-getting-started	18	Learn SAME itself — the universal on-ramp
claude-code-power-user	50	Claude Code workflows and operational patterns
ai-agent-architecture	56	Agent design, orchestration, memory strategies
api-design-patterns	56	REST, GraphQL, auth, rate limiting, and more
typescript-fullstack-patterns	55	Full-stack TypeScript patterns and best practices
engineering-management-playbook	59	Engineering leadership and team management
personal-productivity-os	117	GTD, time blocking, habit systems
security-audit-framework	61	Security review checklists and frameworks

Plus 9 more. Browse all 17 seeds on GitHub.

Privacy

All data stays on your machine. SAME creates a three-tier privacy structure:

Directory	Indexed	Committed	Use for
Your notes	Yes	Your choice	Docs, decisions, research
_PRIVATE/	No	No	API keys, credentials
research/	Yes	No	Strategy, analysis

No telemetry. No cloud. Path traversal blocked. Config files written with owner-only permissions.

More

<details> <summary><strong>Full CLI Reference</strong></summary>

Command	Description
same init	Set up SAME for your project
same demo	See SAME in action with sample notes
same tutorial	7 hands-on lessons
same ask <question>	Ask a question, get cited answers
same search <query>	Search your notes
same search --all <query>	Search across all vaults
same status	See what SAME is tracking
same doctor	Run diagnostic checks
same claim <path> --agent <name>	Advisory file ownership for multi-agent
same pin <path>	Always include a note in sessions
same graph stats	Knowledge graph diagnostics
same web	Local web dashboard
same seed list	Browse available seed vaults
same seed install <name>	Install a seed vault
same vault list|add|remove|default	Manage multiple vaults
same guard settings set push-protect on	Enable push protection
same consolidate	Merge related notes into knowledge summaries
same brief	AI-generated orientation briefing
same health	Vault health score with trust/provenance analysis
same stale	List all stale notes in your vault
same search --trust stale	Filter search by trust state
same search --type decision	Filter search by content type
same ignore	View/manage .sameignore patterns
same facts	View, search, and manage extracted facts
same config set <key> <value>	Set config values from CLI
same brief --no-llm	Structured briefing without LLM
same tips	Best practices for vault hygiene and security
same reindex [--force]	Rebuild search index
same repair	Back up and rebuild database
same update	Update to latest version
same completion [bash|zsh|fish]	Shell completions

</details> <details> <summary><strong>Configuration</strong></summary>

SAME uses .same/config.toml, generated by same init:

[vault]
path = "/home/user/notes"
handoff_dir = "sessions"
decision_log = "decisions.md"

[embedding]
provider = "ollama"           # "ollama", "openai", "openai-compatible", or "none"
model = "nomic-embed-text"

[memory]
max_token_budget = 800
max_results = 2

Supported embedding models: nomic-embed-text (default), snowflake-arctic-embed2, mxbai-embed-large, all-minilm, text-embedding-3-small (OpenAI), and more.

Configuration priority (highest wins): CLI flags > Environment variables > Config file > Defaults

</details> <details> <summary><strong>More Install Options</strong></summary>

# Docker
git clone --depth 1 https://github.com/sgx-labs/statelessagent.git
cd statelessagent && docker build -t same .

# Build from source (requires Go 1.25+)
git clone --depth 1 https://github.com/sgx-labs/statelessagent.git
cd statelessagent && make install

</details> <details> <summary><strong>Troubleshooting</strong></summary>

Start with same doctor -- it runs 20+ checks and tells you what's wrong.

"No vault found" -- Run same init from inside your notes folder, or set VAULT_PATH=/path/to/notes.

"Ollama not responding" -- SAME falls back to keyword search automatically. Test with curl http://localhost:11434/api/tags.

Hooks not firing -- Run same setup hooks to reinstall. Verify with same status.

Database issues -- Run same repair to back up and rebuild.

</details> <details> <summary><strong>SAME vs. Alternatives</strong></summary>

	SAME	mem0	Letta	CLAUDE.md
Setup	1 command	pip + config	pip or Docker	Edit file
Runtime deps	None	Python + vector DB	Python + SQLAlchemy	None
Offline	Full	Not default	With local models	Yes
Cloud required	No	Default yes	No	No
Telemetry	None	Default ON	Yes	None
MCP tools	19	9	Client only	No
Memory integrity	Provenance + trust	No	No	No
Knowledge graph	Built-in	Requires Neo4j	No	No
Cross-tool memory	Yes	API only	No	Claude only
Runs on Pi	Yes (~14MB)	No	No	Yes

</details> <details> <summary><strong>Eval Methodology</strong></summary>

Internal evaluation on 105 tuning cases. Held-out validation: 93.3% Recall@5 on 30 blind test cases (see eval/METHODOLOGY.md).

Metric	Value	Dataset
Recall@5 (keyword)	100%	Internal (68 cases)
Recall@5 (semantic)	84%	Internal (68 cases)
MRR (keyword)	0.65	Internal (68 cases)
Recall@5	90%	Held-out (30 blind cases)

All evaluation uses synthetic vault data. No user data used.

</details>

Links

• Website
• Telegram Bot Plugin
• SeedVaults
• Discord
• Changelog

Contributing

Contributions welcome. Open an issue or start a discussion.

git clone https://github.com/sgx-labs/statelessagent.git
cd statelessagent
make build && make test

See SECURITY.md for security-related reports.

Support

Buy me a coffee | GitHub Sponsors

License

BSL 1.1. Free for personal, educational, hobby, research, and evaluation use. Converts to Apache 2.0 on 2030-02-02. See LICENSE.

---

<a href="https://glama.ai/mcp/servers/@sgx-labs/statelessagent"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@sgx-labs/statelessagent/badge" /> </a>