SAME Documentation

SAME (Stateless Agent Memory Engine) is a local-first persistent memory system for AI coding agents. It gives tools like Claude Code, Cursor, Windsurf, Codex CLI, and Gemini CLI the ability to remember decisions, context, and patterns across sessions. ~12MB Go binary. SQLite + vector embeddings (Ollama, OpenAI, or any compatible provider). Your data never leaves your machine.

Quickstart #

Get running in minutes. No accounts, no API keys.

curl -fsSL statelessagent.com/install.sh | bash

Then explore the interactive demo:

same demo

Or start using it immediately with a project:

# Initialize SAME in your project directory
cd ~/my-project && same init

# Set up Claude Code integration (hooks + MCP)
same setup hooks
same setup mcp

# Start Claude Code — SAME activates automatically
claude

On your first session, SAME orients the agent with relevant context (~200 tokens). On your second session, it surfaces the handoff from the first. By session 10, your agent knows your architecture, your decisions, and your patterns.

See the homepage for the interactive terminal demo showing SAME in action.

What's New in v0.12.0 #

• Memory integrity — Provenance tracking records where notes came from (file sources, SHA256 hashes). Trust states: validated, stale, contradicted, unknown. Source divergence detection flags when source files change.
• Trust-aware retrieval — Stale notes rank 25% lower, contradicted notes rank 60% lower. Trust state returned on all search results.
• 5 new MCP tools — save_kaizen, mem_consolidate, mem_brief, mem_health, mem_forget (17 total).
• same health command — Vault health score with trust analysis and recommendations.
• same kaizen command — Continuous improvement tracking — log friction, bugs, and ideas with provenance.
• Thinking model compatibility — Works with reasoning models like o1 and DeepSeek-R1. Thinking tokens are stripped automatically.
• Graph LLM enrichment — Use an LLM for richer knowledge graph extraction. Control with SAME_GRAPH_LLM env var.

Full changelog: CHANGELOG.md

Installation #

curl -fsSL statelessagent.com/install.sh | bash

npm install -g @sgx-labs/same

irm statelessagent.com/install.ps1 | iex

mkdir -p ~/.local/bin
curl -fsSL https://github.com/sgx-labs/statelessagent/releases/latest/download/same-darwin-arm64 -o ~/.local/bin/same
chmod +x ~/.local/bin/same
export PATH="$HOME/.local/bin:$PATH"

mkdir -p ~/.local/bin
curl -fsSL https://github.com/sgx-labs/statelessagent/releases/latest/download/same-linux-amd64 -o ~/.local/bin/same
chmod +x ~/.local/bin/same
export PATH="$HOME/.local/bin:$PATH"

git clone --depth 1 https://github.com/sgx-labs/statelessagent.git
cd statelessagent && make install

How It Works #

SAME sits between your AI tools and a local knowledge vault. It indexes your markdown notes, captures decisions as you work, and surfaces relevant context at session start.

Session lifecycle

Three automatic phases drive the memory loop:

1. Session Start — Loads vault context, registers this instance, detects other active instances, injects relevant decisions (~200 tokens), surfaces last session handoff.
2. During Session — Agent-driven search via MCP. Zero auto-injection per prompt. The agent queries SAME only when it needs context. Zero tokens overhead per turn.
3. Session End — Extracts new decisions, generates handoff summary, logs session to vault, deregisters instance. Graceful recovery if skipped.

Hooks vs MCP — two integration points

SAME connects to your AI tools in two complementary ways:

• Hooks are automatic triggers at session start and stop. They inject context and capture decisions without the agent doing anything. Currently supported by Claude Code.
• MCP (Model Context Protocol) provides on-demand tools the agent can call mid-session — search notes, save decisions, create handoffs. Works with any MCP client: Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI, and more.

Claude Code gets both (hooks + MCP) for the richest experience. Cursor, Windsurf, Codex CLI, and Gemini CLI use MCP only. Use same init --mcp-only to skip hooks.

Ranking — the 6-gate evaluation chain

Not every prompt needs context. SAME evaluates whether to surface anything at all through a 6-gate chain:

1. Relevance gate — Is the prompt related to indexed knowledge?
2. Distance threshold — Are the nearest embeddings close enough to matter?
3. Composite scoring — Blend of semantic similarity, keyword overlap, and recency
4. Gap detection — Is the best result meaningfully better than the second?
5. Token budget — Does the result fit within the configured budget?
6. Staleness check — Is the note fresh enough to be trustworthy?

~80% of prompts are correctly skipped. When SAME speaks, it matters.

Keyword-only mode

No embedding provider? SAME works out of the box with SQLite FTS5 keyword search. All core features work — session handoffs, decisions, pinned notes, context surfacing. Add Ollama, OpenAI, or any OpenAI-compatible provider when you want semantic search.

Key Concepts #

What is a vault?

A vault is simply a directory of markdown files. It can be your project root, an Obsidian vault, a Logseq graph, or any folder containing .md files. When you run same init, SAME creates a .same/ subdirectory for its database and config — your existing files are never modified.

SAME auto-generates some files into your vault:

• sessions/ — session handoffs (auto-created at session end)
• decisions.md — structured decision log (auto-appended)

You can also write your own notes — architecture docs, patterns, research — and SAME will index and surface them when relevant.

## Use cursor-based pagination (not offset)

**Date:** 2026-01-15
**Context:** API pagination for transactions list
**Decision:** Cursor-based pagination using `created_at` + `id` composite key
**Rationale:** Offset pagination causes count(*) on large tables. Rejected after prod incident on 2026-01-12.
**Status:** Accepted

# Session Handoff: Auth Refactor

**Left off at:** Refresh token migration — routes done, middleware needs update
**Key files:** src/middleware/auth.go, src/routes/refresh.go
**Blockers:** Integration tests need new token fixtures
**Decisions made:** Context-based auth pattern (replacing header injection)
**Next steps:** Update middleware, add test fixtures, deploy to staging

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI tools call external tools. Think of it like a plugin system. SAME registers itself as an MCP server so your AI agent can search your notes, save decisions, and create handoffs — without you doing anything manually. Transport is stdio (no network server, no HTTP ports).

What is Ollama?

Ollama runs AI models locally on your machine. SAME uses it to convert your notes into numerical representations (embeddings) so it can find semantically similar content — not just keyword matches. For example, searching for "throttling" can find a note about "rate limiting."

Ollama is optional. Without it, SAME uses keyword search (SQLite FTS5). With it, you get semantic search. Install: brew install ollama on macOS, or see ollama.ai/download. SAME pulls nomic-embed-text (~270MB) automatically on first use.

Features #

* Semantic mode requires Ollama; keyword fallback is automatic.

Memory integrity

SAME tracks where knowledge comes from and whether it's still trustworthy:

• Provenance tracking — Records file sources and SHA256 hashes for every note. Know exactly where each piece of knowledge originated.
• Trust states — Each note carries a trust state: validated, stale, contradicted, or unknown.
• Source divergence detection — When source files change on disk, SAME flags affected notes as potentially stale.

Trust-aware retrieval

Search results are weighted by trust state. Stale notes rank 25% lower. Contradicted notes rank 60% lower. Trust state is returned on all search results so your agent can reason about knowledge quality, not just relevance.

CLI Reference #

All commands are run as same <command>. Run same --help for the full list.

Setup

Commands you run once during initial setup:

Search & Query

Find and retrieve knowledge from your vault:

Note Management

Create, pin, and organize notes in your vault:

Vault Management

Manage multiple vaults for different projects. Each project gets its own isolated database, auto-detected by directory:

Seed Vaults

Install pre-built knowledge vaults:

Knowledge Graph

Inspect and traverse relationships between notes, concepts, and decisions:

Configuration

Security & Guard

Push protection for multi-agent environments:

Maintenance & Utilities

MCP Tools #

SAME exposes 17 tools via MCP (Model Context Protocol). Your AI agent calls these tools on-demand to search, read, and write to your vault.

same mcp --vault /path/to/notes

Read tools (9)

Write tools (4)

Memory management tools (4)

MCP configuration examples

SAME registers itself automatically via same setup mcp. If you need to configure manually:

{
  "mcpServers": {
    "same": {
      "command": "same",
      "args": ["mcp", "--vault", "/path/to/your/notes"]
    }
  }
}

{
  "mcpServers": {
    "same": {
      "command": "same",
      "args": ["mcp", "--vault", "/path/to/your/notes"]
    }
  }
}

Works With #

Configuration #

Configuration lives at .same/config.toml in your vault root. Edit with same config edit.

[vault]
path = "/home/user/notes"
handoff_dir = "sessions"          # where session handoffs are saved
decision_log = "decisions.md"     # where decisions are logged

[ollama]
url = "http://localhost:11434"    # must be localhost

[embedding]
provider = "ollama"               # "ollama", "openai", "openai-compatible", "llama.cpp", "vllm", "lm-studio"
model = "nomic-embed-text"        # embedding model name

[memory]
max_token_budget = 800            # max tokens injected at session start
max_results = 2                   # max notes surfaced per query
distance_threshold = 16.2         # max embedding distance (lower = stricter)
composite_threshold = 0.65        # min composite score (higher = stricter)

[hooks]
context_surfacing = true          # inject context at session start
decision_extractor = true         # auto-extract decisions at session end
handoff_generator = true          # auto-generate handoff at session end
feedback_loop = true              # track note usefulness
staleness_check = true            # flag outdated notes

Environment variables

Override config via environment. Priority order:

1. CLI flags (--vault)
2. Environment variables (VAULT_PATH, OLLAMA_URL, SAME_*)
3. Config file (.same/config.toml)
4. Built-in defaults

Precision profiles

Tune how aggressively SAME surfaces context:

Display modes

Control output verbosity during context surfacing:

Privacy & Security #

Three-tier privacy structure

Security hardening

• Local-only architecture — no outbound network calls from SAME
• Ollama localhost-only — embedding never leaves 127.0.0.1
• stdio-only MCP transport — no network ports opened, no HTTP server
• Path traversal blocked across all tools
• Dot-directory writes blocked
• Symlink escapes prevented
• Error messages sanitized — no internal paths leak
• Config files use owner-only permissions (0o600)
• Prompt injection patterns scanned before context injection
• No telemetry, no analytics, no phone-home
• No accounts, no signup, no API keys for SAME itself
• Vault files never modified — SAME never changes your existing notes

Troubleshooting #

FAQ #

same vault add work ~/work-notes
same vault add personal ~/personal-notes
same vault default work

Eval Methodology #

All metrics are measured against a ground-truth eval harness, not estimated.

Harness: 105 ground-truth test cases against a 273-note vault. Tuning constants: maxDistance=16.3, minComposite=0.70, gapCap=0.65.

When SAME surfaces context, it's almost always relevant. When it stays quiet, it's almost always right to. The eval methodology is published on GitHub — challenge it.

Community & Support #

• Discord — community chat, support, feature requests
• GitHub Discussions — longer-form questions and ideas
• GitHub Issues — bug reports
• GitHub Sponsors
• Buy me a coffee

License

BSL 1.1 (source-available). Free for personal, educational, hobby, research, evaluation, and commercial use by individuals and small teams. Converts to Apache 2.0 on 2030-02-02. Same model as MariaDB, CockroachDB, HashiCorp.

Built with

Go · SQLite + sqlite-vec · Ollama / OpenAI