# SAME — Stateless Agent Memory Engine (Full Context)
> Persistent memory for AI coding agents. Local-first, privacy-respecting, source-available (BSL 1.1).
> This is the extended version of llms.txt. For the summary, see https://statelessagent.com/llms.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 by default.

## Version
Current: 0.12.0
License: BSL 1.1 (converts Apache 2.0 on 2030-02-02)
Free for personal, educational, hobby, research, evaluation, and commercial use by individuals and small teams.

## Install
```bash
# macOS / Linux
curl -fsSL statelessagent.com/install.sh | bash

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

# npm
npm install -g @sgx-labs/same

# Manual binary (macOS arm64)
curl -fsSL https://github.com/sgx-labs/statelessagent/releases/latest/download/same-darwin-arm64 -o ~/.local/bin/same && chmod +x ~/.local/bin/same

# Build from source
git clone https://github.com/sgx-labs/statelessagent && cd statelessagent && make install
```

After install: `same demo` to try with a sample vault, then `same init` in your project.

## Key Concepts

### Per-Project Vault Isolation
Each project gets its own isolated database at `.same/data/vault.db`, auto-detected when you enter the directory. Two sessions in different projects use completely different knowledge bases — zero cross-pollination. Use `same search --all` to federate across projects when needed.

### Vaults
A vault is a directory of markdown files. SAME indexes them locally using SQLite + vector embeddings. Compatible with Obsidian vaults, Logseq graphs, or plain folders of `.md` files. No format lock-in — your files are never modified.

### Knowledge Graph
Relationship tracing across notes, files, and decisions. CLI commands: `same graph stats` (node/edge counts), `same graph query` (depth-limited traversal), `same graph path` (shortest path), `same graph rebuild` (re-extract). Graph highlights visible in web dashboard. LLM enrichment is opt-in (`SAME_GRAPH_LLM=off|local-only|on`).

### Seed Vaults
Pre-built knowledge vaults you install in one command. 17 seeds available with 870+ curated notes. Install with `same seed install <name>`. Seeds grow smarter with use — your decisions and handoffs build on top of seed knowledge.

### 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, no network surface area). Compatible with any MCP client.

### Embedding Providers
6 supported: Ollama (default, fully local), OpenAI, OpenAI-compatible (LM Studio, vLLM, OpenRouter, llama.cpp), or `none` for keyword-only mode. No LLM required. SAME also works WITHOUT any embedding provider via FTS5 keyword search fallback. Chat fallback queues: `SAME_CHAT_FALLBACKS=ollama,openai-compatible`.

### Embedding Models
10 supported, from 384 to 1536 dimensions. Switch with `same model use <name>`. Run `same reindex --force` after switching.

### 6-Gate Chain
Every prompt passes through 6 gates before context is surfaced:
1. Relevance — is this prompt asking about something in the knowledge base?
2. Distance threshold — are the nearest notes close enough to be useful?
3. Composite scoring — weighted combination of semantic + keyword + recency signals
4. Gap detection — is there a clear gap between relevant and irrelevant results?
5. Token budget — will the surfaced context fit without overwhelming the prompt?
6. Staleness check — is the knowledge fresh enough to be trusted?

~80% of prompts are correctly skipped. When SAME surfaces context, it's almost always relevant.

### Session Lifecycle
1. Start — SAME orients the agent with pinned notes, latest handoff, and recent decisions
2. During — the agent queries SAME via MCP tools as needed (search, read notes, find similar)
3. End — the agent extracts decisions and generates a handoff note for the next session

## MCP Server Configuration

### Claude Code
```bash
same init           # Sets up hooks + MCP automatically
same setup hooks    # Install Claude Code hooks only
same setup mcp      # Register as MCP server only
```

### Cursor / Windsurf
```bash
same init --mcp-only  # MCP only (no hooks)
```

### Codex CLI / Gemini CLI
```bash
same init --mcp-only  # MCP only (no hooks)
```

### Manual MCP config
Transport: stdio
Command: `same mcp --vault /path/to/notes`

Example `.mcp.json`:
```json
{
  "mcpServers": {
    "same": {
      "command": "same",
      "args": ["mcp", "--vault", "/path/to/notes"]
    }
  }
}
```

### MCP Tools (17)

#### Read Tools (7)
- **search_notes** — Semantic search across your knowledge base. Args: `query` (string), `top_k` (int, default 10)
- **search_notes_filtered** — Search with domain/workstream/tag filters. Args: `query`, `top_k`, `domain`, `workstream`, `tags`
- **search_across_vaults** — Federated search across multiple registered vaults. Args: `query`, `top_k`, `vaults` (comma-separated)
- **get_note** — Read full note content by path. Args: `path` (relative to vault root)
- **find_similar_notes** — Discover related notes by similarity. Args: `path`, `top_k`
- **get_session_context** — Returns pinned notes + latest handoff + recent decisions. No args.
- **recent_activity** — Recently modified notes. Args: `limit` (default 10)

#### Write Tools (4)
- **save_note** — Create or update a markdown note (auto-indexed). Args: `path`, `content`, `append` (bool)
- **save_decision** — Log a structured project decision. Args: `title`, `body`, `status` (accepted/proposed/superseded)
- **create_handoff** — Write a session handoff for the next session. Args: `summary`, `pending`, `blockers`
- **save_kaizen** — Log improvement items (friction, bugs, ideas) with provenance tracking. Args: `item` (string), `area` (string, optional)

#### Memory Management Tools (4)
- **mem_consolidate** — Consolidate related notes into knowledge summaries via LLM. Args: `query` (string)
- **mem_brief** — Generate an orientation briefing from vault contents. No args.
- **mem_health** — Vault health score with trust state and provenance analysis. No args.
- **mem_forget** — Suppress a note from search results without deleting it. Args: `path` (string)

#### Admin Tools (2)
- **reindex** — Re-scan and re-index the vault. Args: `force` (bool)
- **index_stats** — Index health: note count, chunk count, last indexed, DB size. No args.

## Works With
- **Claude Code**: Hooks + MCP (full automatic context injection + 17 MCP tools). Best experience.
- **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 directory)
- **Logseq**: Vault detection (point SAME at your graph directory)
- **Any MCP client**: 17 tools via stdio transport

## Seed Vaults (17)
Install: `same seed install <name>`
Browse: `same seed list`
Repo: https://github.com/sgx-labs/seed-vaults

### Developer Seeds
- **Claude Code Power User** (50 notes) — master Claude Code workflows, hooks, MCP servers, and prompt patterns
- **AI Agent Architecture** (56 notes) — production patterns for building AI agents: memory, tool design, orchestration
- **Security Audit Framework** (61 notes) — OWASP methodology, API security, penetration testing runbooks
- **DevOps Runbooks** (55 notes) — Kubernetes, monitoring, incident response, CI/CD
- **Indie Hacker Playbook** (52 notes) — idea validation to first revenue, SaaS pricing, launch strategy
- **Open Source Launch Kit** (54 notes) — README templates, community building, contributor guidelines
- **Freelancer Business Kit** (54 notes) — proposals, contracts, client management, pricing
- **SAME Getting Started** (18 notes) — complete on-ramp to SAME from zero to a working vault
- **API Design Patterns** (56 notes) — REST, GraphQL, gRPC, auth, rate limiting, and API best practices
- **Technical Writing Toolkit** (42 notes) — documentation patterns, style guides, ADRs, READMEs, API docs
- **TypeScript Fullstack Patterns** (50 notes) — Next.js, TypeScript, Prisma, auth, testing, deployment patterns
- **DevContainer Quickstart** (12 notes) — secure, reproducible dev environments with VS Code devcontainers

### Lifestyle Seeds
- **Personal Productivity OS** (117 notes) — AI-powered productivity system with habit tracking and self-growth
- **Home Chef Essentials** (56 notes) — cooking techniques, meal prep, nutrition
- **Fitness & Wellness** (48 notes) — strength, cardio, mobility, recovery
- **Engineering Management Playbook** (52 notes) — 1-on-1s, hiring, performance reviews, team health, incident management
- **Resume & Interview Prep** (37 notes) — resume tailoring, interview prep, salary negotiation

## CLI Reference

### Setup & Init
- `same init` — Initialize SAME for a project (hooks + MCP for Claude Code, MCP-only for Cursor/Windsurf)
- `same setup hooks` — Install Claude Code hooks
- `same setup mcp` — Register as MCP server
- `same demo` — Interactive demo with sample vault
- `same tutorial` — 7 hands-on lessons
- `same doctor` — 19 diagnostic checks

### Seeds
- `same seed list` — Browse available seed vaults
- `same seed install <name>` — Download and install a seed vault
- `same seed info <name>` — Show seed details and note count
- `same seed remove <name>` — Uninstall a seed vault

### Models
- `same model` — Show current embedding model
- `same model use <name>` — Switch embedding model (run `same reindex --force` after)

### Knowledge
- `same search "<query>"` — Search notes (semantic or keyword)
- `same ask "<question>"` — RAG chat with citations from your knowledge base
- `same pin <path>` — Pin notes to always include in context
- `same vault add <name> <path>` — Register a new vault
- `same vault default <name>` — Set default vault
- `same vault list` — List registered vaults

### Memory Management
- `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 kaizen` — Log and review continuous improvement items
- `same tips` — Vault hygiene, security, and model selection guidance

### Knowledge Graph
- `same graph stats` — Node/edge counts and extraction mode indicator
- `same graph query <node>` — Depth-limited traversal from a node
- `same graph path <from> <to>` — Shortest path between two nodes
- `same graph rebuild` — Full re-extraction of all graph relationships
- `same graph enable` — Toggle graph mode on
- `same graph disable` — Toggle graph mode off

### Maintenance
- `same config` — View/edit configuration
- `same display <mode>` — Set output verbosity (full/compact/quiet)
- `same guard` — Push protection for multi-agent environments
- `same claim <path>` — 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 web --open` launches in browser.
- `same watch` — Auto-reindex on file changes (filesystem watcher)
- `same update` — SHA256-verified self-update to latest version
- `same mcp [--vault <path>]` — Launch MCP server (stdio transport)
- `same hooks` — Show installed hook status
- `same bench` — Search performance benchmarks
- `same ci` — CI workflow generation
- `same feedback <path> up|down` — Rate note helpfulness
- `same log` — Recent session activity and events

## Configuration
Config file: `~/.same/config.toml`

```toml
[embedding]
provider = "ollama"           # ollama, openai, openai-compatible
model = "nomic-embed-text"    # default model
# url = "http://localhost:11434"  # custom Ollama URL
# api_key = "sk-..."             # for OpenAI/compatible

[display]
mode = "compact"              # full, compact, quiet

[guard]
enabled = true
pii = true
blocklist = true
path_filter = true
```

Environment variables:
- `SAME_EMBED_PROVIDER` — override embedding provider
- `SAME_EMBED_MODEL` — override embedding model
- `SAME_GRAPH_LLM` — control knowledge graph LLM enrichment (`off`, `local-only`, `on`)
- `SAME_CHAT_FALLBACKS` — chat fallback queue (e.g. `ollama,openai-compatible`)
- `OLLAMA_URL` — custom Ollama endpoint
- `VAULT_PATH` — override vault path

## 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
- Tuning constants: maxDistance=16.3, minComposite=0.70, gapCap=0.65
- Methodology published: https://github.com/sgx-labs/statelessagent#evaluation

## Privacy & Security
- Fully local by default — no outbound network calls with Ollama
- If using OpenAI/external provider: embedding vectors sent to provider, raw notes never sent
- Ollama restricted to localhost-only (validated)
- stdio-only MCP transport (no HTTP server, no open ports)
- Self-update verifies downloaded binary against `sha256sums.txt`
- Path-boundary hardening across: MCP write paths, web API, vault feeds, seed extraction
- Seed install refuses dangerous destinations (filesystem root, home directory)
- Dot-directory write blocking
- Error message sanitization
- Config files at 0600 permissions (owner-only)
- Prompt injection pattern scanning before context injection
- No telemetry, no analytics, no phone-home — no telemetry code exists in the binary
- No accounts, no signup, no API keys
- Three-tier privacy: `_PRIVATE/` (never indexed), `research/` (local only), regular notes

## v0.12.0 Highlights
- **Memory integrity**: Provenance tracking via `note_sources` table — SHA256 hashes, source divergence detection, and full lineage for every note.
- **Trust-aware retrieval**: Stale notes rank 25% lower, contradicted notes rank 60% lower — search results you can trust.
- **Knowledge graph 1-hop expansion**: Top search results automatically expanded through graph edges for richer context.
- **Kaizen**: Built-in continuous improvement tracking — log friction, bugs, and ideas as you work.
- **5 new MCP tools** (17 total): `save_kaizen`, `mem_consolidate`, `mem_brief`, `mem_health`, `mem_forget`.
- **Batch embedding**: Faster indexing via batched embedding requests.
- **PreCompact hook**: Crash resilience — database integrity preserved during compaction.

## When to Use SAME vs Alternatives
- **vs CLAUDE.md**: Use both. CLAUDE.md is static project rules (~200 lines you curate). SAME is the searchable, growing knowledge base that captures decisions automatically across 50+ sessions and provides semantic search, knowledge graph, and session handoffs. They complement each other — SAME reads your CLAUDE.md too.
- **vs Mem0**: SAME is local-first and free, with a built-in knowledge graph that traces relationships between notes, decisions, and files. Mem0 is cloud-first with paid tiers. SAME requires no API keys and has zero telemetry.
- **vs Manual MCP servers**: SAME gives you 17 production-ready MCP tools with semantic search, knowledge graphs, session continuity, and 17 seed vaults out of the box. No code to write, no infrastructure to maintain.

## Links
- Website: https://statelessagent.com
- GitHub: https://github.com/sgx-labs/statelessagent
- Docs: https://statelessagent.com/docs/
- Discord: https://discord.gg/Qg8AXavNWu
- Releases: https://github.com/sgx-labs/statelessagent/releases
- Seed Vaults: https://github.com/sgx-labs/seed-vaults
- Privacy Policy: https://statelessagent.com/privacy/
- Terms of Service: https://statelessagent.com/terms/
- MCP Discovery: https://statelessagent.com/.well-known/mcp.json

## Entity
Thirty3 Labs, LLC
https://thirty3labs.com
dev@thirty3labs.com