Stateless Agent Memory Engine (SAME)
The SAME server provides persistent memory and knowledge management for AI coding agents, enabling context to survive across sessions.
Search & Discovery
Semantic/keyword search across your knowledge base, with filters for domain, workstream, tags, agent attribution, trust state, or content type
Federated search across multiple registered vaults simultaneously
Find notes semantically similar to a given note
Read the full content of a specific note by path
Session & Orientation
Retrieve pinned notes, latest handoff, and recent decisions to orient a new session
List recently modified notes to track activity
Generate concise orientation briefings summarizing recent activity, open decisions, and key context
Writing & Saving
Create or update markdown notes with optional provenance tracking and agent attribution
Log structured project decisions (accepted/proposed/superseded)
Write session handoff notes capturing what was done, what's pending, and blockers
Log friction points, bugs, or improvement ideas with source attribution
Memory Maintenance
Consolidate related notes, merge duplicates, resolve contradictions, and extract key facts
Suppress outdated or irrelevant notes from search results without deleting them
Re-index all markdown notes (incremental or full rebuild)
Check vault health with a score (0–100), recommendations, index stats, and last indexed timestamps
Provides multi-agent file claims, advisory locks, and push protection within Git repositories to prevent AI agents from overwriting each other's work while tracking context provenance.
Indexes and searches local Markdown notes to provide AI agents with persistent memory, surfacing relevant context, project decisions, and session handoffs.
Integrates with Ollama to provide local semantic search capabilities through embeddings, enabling higher-precision retrieval of relevant notes and context.
Utilizes pre-commit hooks to perform PII scanning, detecting secrets and personal data before they are committed to the repository.
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 | iexOr 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.
Related MCP server: Nowledge Mem
See It Work
same demoIndexing 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 healthshows 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 --mcpenables 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 manuallyHow 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 |
|
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 |
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 automaticallyCursor / 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 |
| Semantic search across your knowledge base |
| Search with domain/tag/agent filters |
| Federated search across multiple vaults |
| Read full note content by path |
| Discover related notes |
| Pinned notes + latest handoff + git state |
| Recently modified notes |
| Create or update a note |
| Log a structured project decision |
| Write a session handoff |
| Re-scan and re-index the vault |
| Index health and statistics |
| Consolidate related notes via LLM |
| Generate orientation briefing |
| Vault health with trust analysis |
| Suppress a note from search results |
| Undo mem_forget (unsuppress a note) |
| List suppressed notes |
| 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 oneSeed | Notes | What you get |
| 18 | Learn SAME itself — the universal on-ramp |
| 50 | Claude Code workflows and operational patterns |
| 56 | Agent design, orchestration, memory strategies |
| 56 | REST, GraphQL, auth, rate limiting, and more |
| 55 | Full-stack TypeScript patterns and best practices |
| 59 | Engineering leadership and team management |
| 117 | GTD, time blocking, habit systems |
| 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 |
| No | No | API keys, credentials |
| Yes | No | Strategy, analysis |
No telemetry. No cloud. Path traversal blocked. Config files written with owner-only permissions.
More
Command | Description |
| Set up SAME for your project |
| See SAME in action with sample notes |
| 7 hands-on lessons |
| Ask a question, get cited answers |
| Search your notes |
| Search across all vaults |
| See what SAME is tracking |
| Run diagnostic checks |
| Advisory file ownership for multi-agent |
| Always include a note in sessions |
| Knowledge graph diagnostics |
| Local web dashboard |
| Browse available seed vaults |
| Install a seed vault |
| Manage multiple vaults |
| Enable push protection |
| Merge related notes into knowledge summaries |
| AI-generated orientation briefing |
| Vault health score with trust/provenance analysis |
| List all stale notes in your vault |
| Filter search by trust state |
| Filter search by content type |
| View/manage .sameignore patterns |
| View, search, and manage extracted facts |
| Set config values from CLI |
| Structured briefing without LLM |
| Best practices for vault hygiene and security |
| Rebuild search index |
| Back up and rebuild database |
| Update to latest version |
| Shell completions |
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 = 2Supported 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
# 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 installStart 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.
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 |
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.
Links
Contributing
Contributions welcome. Open an issue or start a discussion.
git clone https://github.com/sgx-labs/statelessagent.git
cd statelessagent
make build && make testSee 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.
Available Tools
17 toolscreate_handoffAIdempotent
Create a session handoff note so the next session picks up where this one left off. Write what you worked on, what's pending, and any blockers.
Args: summary: What was accomplished this session pending: What's left to do (optional) blockers: Any blockers or open questions (optional) agent: Optional writer attribution stored in frontmatter (e.g. 'codex')
Returns path to the handoff note.
Inputs: summary (required), pending, blockers, agent.
find_similar_notesARead-only
Find notes that cover similar topics to a given note. Use this to discover related context, find notes that might conflict, or build a broader picture of a topic.
Args: path: Relative path of the source note top_k: Number of similar notes (default 5, max 100)
Returns list of related notes ranked by similarity.
Inputs: path (required), top_k (required).
get_noteARead-only
Read the full content of a note. Use this after search_notes returns a relevant result and you need the complete text. Paths are relative to the vault root.
Args: path: Relative path from vault root (as returned by search_notes)
Returns full markdown text content.
Inputs: path (required).
get_session_contextARead-only
Get orientation context for a new session. Returns pinned notes, the latest handoff, and recent decisions — everything you need to pick up where the last session left off.
Returns structured session context.
index_statsARead-only
Check the health and size of the note index. Use this to verify the index is up to date or to report stats to the user.
Returns note count, chunk count, last indexed timestamp, embedding model info, and database size.
If the user reports problems, suggest they run same doctor for diagnostics. For bugs, direct them to: https://github.com/sgx-labs/statelessagent/issues
mem_briefARead-only
Get an orientation briefing of what matters right now. Shows recent activity, open decisions, and key context. Use this at the start of a session to understand current project state.
Args: max_items: Maximum items per section (default 5)
Returns a concise briefing generated from vault contents. (experimental)
Inputs: max_items (required).
mem_consolidateADestructive
Consolidate related notes in the vault. Merges duplicates, resolves contradictions, extracts key facts. Creates new knowledge files without modifying originals. Use this when the vault has many similar or overlapping notes.
Args: dry_run: Preview what would be consolidated without writing files (default false) threshold: Similarity threshold for grouping notes, 0.0-1.0 (default 0.75)
Returns consolidation summary with groups found, facts extracted, and conflicts resolved. (experimental)
Inputs: dry_run (required), threshold (required).
mem_forgetAIdempotent
Suppress a memory so it won't be surfaced in normal search. The note is not deleted -- it's marked as suppressed and will only appear if explicitly requested. Use this for outdated, incorrect, or irrelevant memories. This is not easily reversible: there is no mem_restore tool.
Args: path: Path of the note to suppress (required) reason: Why this memory is being suppressed (optional)
Returns confirmation of suppression. (experimental)
Inputs: path (required), reason.
mem_healthARead-only
Check the health of the memory vault. Returns a health score (0-100) and actionable recommendations. Use this to determine if the vault needs consolidation, reindexing, or cleanup.
Returns health score, key metrics, and recommendations. (experimental)
recent_activityARead-only
Get recently modified notes. Use this to see what's changed recently or to orient yourself at the start of a session.
Args: limit: Number of recent notes (default 10, max 50)
Returns list of recently modified notes with titles and paths.
Inputs: limit (required).
reindexADestructive
Re-scan and re-index all markdown notes. Use this if the user has added or changed notes and search results seem stale. Incremental by default (only re-embeds changed files).
Args: force: Re-embed all files regardless of changes (default false)
Returns indexing statistics.
Inputs: force (required).
save_decisionAIdempotent
Log a project decision. Appends to the decision log so future sessions can find it.
Args: title: Short decision title (e.g. 'Use JWT for auth') body: Full decision details — what was decided, why, alternatives considered status: Decision status — 'accepted', 'proposed', or 'superseded' (default 'accepted') agent: Optional writer attribution stored in frontmatter (e.g. 'codex')
Returns confirmation.
Inputs: title (required), body (required), status (required), agent.
save_kaizenAIdempotent
Log a friction point, bug, or improvement idea discovered during work. SAME tracks provenance — if the source files change later, the item is automatically flagged as potentially addressed.
Args: description: What was observed (required) area: Area of the codebase (e.g. 'indexer', 'config', 'hooks') (optional) agent: Who observed it (optional) sources: Related file paths for provenance tracking (optional)
Returns confirmation with the file path.
Inputs: description (required), area, agent, sources.
save_noteADestructive
Create or update a markdown note in the vault. The note is written to disk and indexed automatically.
Optionally specify source files to enable provenance tracking — SAME will flag this note as stale if sources change.
Args: path: Relative path within the vault (e.g. 'decisions/auth-approach.md') content: Markdown content to write append: If true, append to existing file instead of overwriting (default false) agent: Optional writer attribution stored in frontmatter (e.g. 'codex') sources: File paths that this note was derived from (optional)
Returns confirmation with the saved path.
Inputs: path (required), content (required), append (required), agent, +1 more.
search_across_vaultsARead-only
Search across multiple registered vaults at once. Use this instead of search_notes when you need context from other projects or want a cross-project view. Vaults must be registered first via the CLI (same vault add <name> <path>).
Args: query: Natural language search query top_k: Number of results (default 10, max 100) vaults: Comma-separated vault aliases to search. Omit to search all registered vaults. Unknown aliases are silently skipped.
Returns ranked results with titles, paths, snippets, and source vault name.
Inputs: query (required), top_k (required), vaults.
search_notesARead-only
Search the user's knowledge base for relevant notes, decisions, and context. Use this when you need background on a topic, want to find prior decisions, or need to understand project architecture.
Args: query: Natural language search query (e.g. 'authentication approach', 'database schema decisions') top_k: Number of results (default 10, max 100)
Returns ranked list of matching notes with titles, paths, and text snippets.
Inputs: query (required), top_k (required).
search_notes_filteredARead-only
Search the user's knowledge base with metadata filters. Use this when you want to narrow results by domain (e.g. 'engineering'), workstream (e.g. 'api-redesign'), tags, agent attribution, trust state, or content type.
Args: query: Natural language search query top_k: Number of results (default 10, max 100) domain: Filter by domain (e.g. 'engineering', 'product') workstream: Filter by workstream/project name tags: Comma-separated tags to filter by agent: Filter by agent attribution (e.g. 'codex', 'claude') trust_state: Filter by trust state (validated, stale, contradicted, unknown) content_type: Filter by content type (decision, handoff, note, research)
Returns filtered ranked list.
Inputs: query (required), top_k (required), domain, workstream, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
There is significant overlap between search_notes, search_notes_filtered, and search_across_vaults—all perform search with varying scopes or filters, which could confuse agents about which to use. Similarly, mem_brief and get_session_context both provide session orientation, though mem_brief is experimental. Other tools like save_note and get_note have clear distinct purposes for write and read operations.
Naming is mixed: some tools use verb_noun (e.g., create_handoff, save_note, search_notes), while others use noun_verb or other patterns (e.g., index_stats, mem_brief, recent_activity). This inconsistency makes the set less predictable, though most names are still readable and descriptive of their functions.
With 17 tools, the count is on the higher side but reasonable for a memory engine covering note management, search, indexing, and session handling. It includes core operations like create, read, update, and search, plus experimental features, which fits the domain without being overly bloated.
The toolset covers key aspects of a memory engine: note CRUD (save_note, get_note), search (multiple variants), indexing (reindex, index_stats), session management (create_handoff, get_session_context), and experimental consolidation/health tools. A minor gap is the lack of a tool to update or delete notes directly (only suppression via mem_forget), but agents can work around this with save_note and append or overwrite.
Maintenance
Related MCP Connectors
Truth-validated, SHA-512-sealed AI memory for Claude & Cursor. Free tier, OAuth, 38 tools.
Provenance-carrying memory for AI agents: corrections supersede, never overwrite. Free, API + MCP.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
A second brain for your AI agent. Shared memory for your team's AI agents, plus public and private knowledge bases — works with ChatGPT, Claude, Cursor and any MCP client.
Related MCP Servers
AlicenseAqualityFmaintenanceAn MCP server that integrates with mem0.ai to help users store, retrieve, and search coding preferences for more consistent programming practices.9661Apache 2.0
Nowledge Memofficial
AlicenseNot gradedqualityDmaintenanceEnables Claude to add and search personal memories through the Nowledge Mem service. Allows users to store and retrieve contextual information across conversations.4MIT- AlicenseAqualityBmaintenanceEnables AI agents to store, retrieve, and connect information in a Neo4j graph database as persistent memory, with semantic relationships, natural language search, and temporal tracking across conversations.9150 npm67MIT
- AlicenseBqualityDmaintenanceProvides project memory management for Claude Desktop, storing memories as Markdown files with intelligent keyword-based retrieval and automatic creation/update decisions by LLM.21MIT