# SAME — Stateless Agent Memory Engine > Persistent memory for AI coding agents. Local-first, privacy-respecting, source-available (BSL 1.1). > For full context including MCP tool schemas and CLI reference, see https://statelessagent.com/llms-full.txt ## Overview SAME gives AI coding agents persistent memory across sessions. It indexes your markdown notes locally, captures decisions as you work, and orients your agent with relevant context automatically. A 6-gate chain evaluates every prompt and only injects context when it adds value. Single Go binary (~12MB). SQLite + vector search. Nothing leaves your machine. ## Version Current: 0.12.0 License: BSL 1.1 (converts Apache 2.0 on 2030-02-02) ## Install curl -fsSL statelessagent.com/install.sh | bash ## Key Concepts - **Per-project vault isolation**: Each project gets its own `.same/` directory with its own SQLite database, auto-detected by directory. Zero cross-pollination between projects. - **Vault**: A directory of markdown files (Obsidian, Logseq, or plain folders). SAME indexes them locally. - **Knowledge Graph**: Relationship tracing across notes. `same graph stats`, `same graph query`, `same graph path`, `same graph rebuild`. Visible in CLI and dashboard. - **Seed Vaults**: Pre-built knowledge vaults you install in one command. 17 seeds, 870+ curated notes. `same seed install `. - **MCP**: Model Context Protocol — an open standard letting AI tools call external tools. SAME registers as an MCP server via stdio transport (no HTTP ports). - **Embedding Providers**: 6 supported — Ollama (default), OpenAI, OpenAI-compatible (LM Studio, vLLM, OpenRouter, llama.cpp), or `none` for keyword-only mode. No LLM required. - **Embedding Models**: 10 supported, from 384 to 1536 dimensions. Switch with `same model use `. - **6-gate chain**: Relevance, distance threshold, composite scoring, gap detection, token budget, staleness check. ~80% of prompts are correctly skipped. - **Session lifecycle**: Start (orient with context) → During (agent queries via MCP) → End (extract decisions, generate handoff). - **Session continuity**: Crash recovery, decision extraction, handoff aging (72h), pinned notes. ## MCP Server Transport: stdio Command: same mcp --vault /path/to/notes ### Tools (17) #### Read (7) - search_notes: Semantic search across your knowledge base - search_notes_filtered: Search with domain/workstream/tag filters - search_across_vaults: Federated search across multiple registered vaults - get_note: Read full note content by path - find_similar_notes: Discover related notes by similarity - get_session_context: Pinned notes + latest handoff + recent activity - recent_activity: Recently modified notes #### Write (4) - save_note: Create or update a markdown note (auto-indexed, with provenance tracking) - save_decision: Log a structured project decision - create_handoff: Write a session handoff for the next session - save_kaizen: Log improvement items (friction, bugs, ideas) with provenance tracking #### Memory Management (4) - mem_consolidate: Consolidate related notes into knowledge summaries via LLM - mem_brief: Generate an orientation briefing from vault contents - mem_health: Vault health score with trust state and provenance analysis - mem_forget: Suppress a note from search results without deleting it #### Admin (2) - reindex: Re-scan and re-index the vault - index_stats: Index health and statistics ## Works With - Claude Code: Hooks + MCP (full automatic context + 17 MCP tools) - Cursor: MCP only (17 MCP tools, use `same init --mcp-only`) - Windsurf: MCP only (17 MCP tools, use `same init --mcp-only`) - Codex CLI: MCP only (17 MCP tools) - Gemini CLI: MCP only (17 MCP tools) - Obsidian: Vault detection (point SAME at your vault) - Logseq: Vault detection (point SAME at your graph) - Any MCP client: 17 tools via stdio transport ## Seed Vaults 17 pre-built knowledge vaults with 870+ curated notes: - Claude Code Power User (50 notes) — master Claude Code workflows and prompt patterns - AI Agent Architecture (56 notes) — production patterns for building AI agents - Personal Productivity OS (117 notes) — AI-powered productivity system - Security Audit Framework (61 notes) — OWASP methodology, API security - DevOps Runbooks (55 notes) — Kubernetes, monitoring, incident response - Indie Hacker Playbook (52 notes) — idea validation to first revenue - Open Source Launch Kit (54 notes) — README templates, community building - Freelancer Business Kit (54 notes) — proposals, contracts, client management - Home Chef Essentials (56 notes) — cooking techniques, meal prep, nutrition - Fitness & Wellness (48 notes) — strength, cardio, mobility, recovery - SAME Getting Started (18 notes) — complete on-ramp from zero to a working vault - API Design Patterns (56 notes) — REST, GraphQL, gRPC, auth, rate limiting - Technical Writing Toolkit (42 notes) — documentation patterns, style guides, ADRs - TypeScript Fullstack Patterns (50 notes) — Next.js, TypeScript, Prisma, auth, testing - Engineering Management Playbook (52 notes) — 1-on-1s, hiring, performance reviews - Resume & Interview Prep (37 notes) — resume tailoring, interview prep, salary negotiation - DevContainer Quickstart (12 notes) — secure, reproducible dev environments Seed repo: https://github.com/sgx-labs/seed-vaults ## When to Use SAME vs Alternatives - **vs CLAUDE.md**: Use both. CLAUDE.md is static project rules (~200 lines). SAME is the searchable, growing knowledge base that captures decisions automatically across 50+ sessions. They complement each other. - **vs Mem0**: SAME is local-first and free. Mem0 is cloud-first with paid tiers. SAME includes a built-in knowledge graph that traces relationships between notes, decisions, and files. - **vs Manual MCP servers**: SAME gives you 17 production-ready MCP tools with semantic search, knowledge graphs, memory integrity, and session continuity out of the box. No code to write. ## v0.12.0 Highlights - Memory integrity: provenance tracking records where knowledge came from (file sources, SHA256 hashes) and flags when sources change - Trust-aware retrieval: stale notes rank lower automatically, contradicted notes rank 60% lower - Knowledge graph 1-hop expansion: top search results are expanded through graph edges to surface related decisions and dependencies - Kaizen: continuous improvement tracking — log friction, bugs, and ideas as you work - 5 new MCP tools: save_kaizen, mem_consolidate, mem_brief, mem_health, mem_forget - Batch embedding requests for faster indexing - Crash resilience: PreCompact hook for session checkpointing ## CLI Commands - same seed list: Browse available seed vaults - same seed install : Download and install a seed vault - same seed info : Show seed details - same seed remove : Uninstall a seed vault - same model: Show current embedding model - same model use : Switch embedding model - same init: Initialize SAME for a project - same demo: Interactive demo - same tutorial: 7 hands-on lessons - same doctor: 19 diagnostic checks - same setup hooks: Install Claude Code hooks - same setup mcp: Register as MCP server - same ask: RAG chat with citations - same search: Search notes (semantic or keyword) - same pin: Pin notes to always include in context - same vault: Manage multiple vaults - same config: View/edit configuration - same display: Set output verbosity (full/compact/quiet) - same graph stats: Knowledge graph node/edge counts - same graph query: Depth-limited graph traversal - same graph path: Shortest path between nodes - same graph rebuild: Re-extract all graph relationships - same kaizen: Log and review continuous improvement items - same health: Vault health score with trust analysis and recommendations - same consolidate: Merge related notes into structured knowledge using LLM - same brief: Orientation briefing of what matters right now - same tips: Vault hygiene, security, and model selection guidance - same graph enable: Toggle graph mode on - same graph disable: Toggle graph mode off - same guard: Push protection for multi-agent environments - same claim: Advisory file claims for multi-agent coordination - same reindex: Rebuild search index - same repair: Back up and rebuild database - same status: Check vault, hooks, MCP, Ollama status - same web: Read-only localhost dashboard to browse, search, and inspect your vault - same update: SHA256-verified self-update - same mcp: Launch MCP server (stdio transport) - same hooks: Show installed hook status - same bench: Search performance benchmarks - same ci: CI workflow generation ## Eval Metrics - Retrieval precision: 99.5% on internal eval (105 synthetic test cases) - Mean Reciprocal Rank: 0.949 - Coverage (recall): 90.5% - Prompt overhead: <200ms - Test harness: 105 ground-truth cases, 273-note vault ## Privacy & Security - Fully local — no outbound network calls - Ollama restricted to localhost - stdio-only MCP transport (no HTTP server) - Path traversal blocked, symlink escapes prevented - Checksum-verified self-update (sha256sums.txt) - Prompt injection pattern scanning before context injection - `_PRIVATE/` content never indexed or surfaced - Config files written with owner-only permissions (0o600) - No telemetry, no analytics, no phone-home - No accounts, no signup, no API keys ## Links - GitHub: https://github.com/sgx-labs/statelessagent - Discord: https://discord.gg/Qg8AXavNWu - Docs: https://statelessagent.com/docs/ - Releases: https://github.com/sgx-labs/statelessagent/releases - MCP Discovery: https://statelessagent.com/.well-known/mcp.json