SAME — Stateless Agent Memory Engine

Persistent project memory for AI coding workflows.

SAME is a local-first memory layer for solo developers, researchers, creatives, and small teams using Claude Code, Cursor, Windsurf, or any MCP client. It indexes your markdown notes, surfaces relevant context in new sessions, and records decisions + handoffs so work continues across restarts. No cloud lock-in. No telemetry. One binary.

See it in 60 seconds

curl -fsSL https://statelessagent.com/install.sh | bash
same demo

same demo creates a temporary vault with sample notes, runs semantic search, and shows your AI answering questions from your notes — all locally, no accounts, no API keys.

Quickstart

# 1. Install (pick one)
curl -fsSL https://statelessagent.com/install.sh | bash   # direct binary
npm install -g @sgx-labs/same                      # or via npm

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

# 3. Verify retrieval
same search "authentication decision"

# 4. Optional: ask with citations (requires chat model/provider)
same ask "what did we decide about authentication?"

# 5. Your AI now remembers (hooks + MCP tools active)
# Start Claude Code, Cursor, or any MCP client — context surfaces automatically

That's it. Your AI now has memory.

Release notes: CHANGELOG.md

Human-First Philosophy

SAME is built around one constraint: your knowledge belongs to you.

• Notes are plain markdown, so your system remains useful even without AI.
• The tool is designed to help you learn by using it, not lock you into opaque automation.
• Local-first defaults keep individuals in control of data and workflow.
• The goal is a better human+AI relationship: symbiotic, practical, and durable.

This is a digital multitool for builders: solo developers, creatives, researchers, and small teams who want capability without giving up ownership.

Design details and architecture rationale: docs/design_context.md

Add to Your AI Tool

Claude Code (hooks + MCP — full experience)

same init          # sets up hooks + MCP in one step

SAME installs 6 Claude Code hooks automatically. Context surfaces on every session start. Decisions extracted on stop. No config file to edit.

Claude Code / Cursor / Windsurf (MCP only)

Or add manually to your MCP config (.mcp.json, .claude/settings.json, Cursor MCP settings):

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

Replace /absolute/path/to/your/notes with the actual path to your project or notes directory. 12 tools available instantly. Works without Ollama (keyword fallback).

Why SAME

The Numbers

Benchmarked against 105 ground-truth test cases. Methodology

How It Works

┌─────────────┐     ┌─────────────────┐     ┌──────────┐     ┌─────────────────┐
│  Your Notes │     │   Embeddings    │     │  SQLite  │     │  Your AI Tool   │
│   (.md)     │────>│ local or cloud  │────>│ (search) │────>│ Claude / Cursor │
│             │     │ provider         │     │ + FTS5   │     │ via Hooks + MCP │
└─────────────┘     └─────────────────┘     └──────────┘     └─────────────────┘
                                              │                    │
                                         ┌────▼────┐          ┌────▼────┐
                                         │ Ranking │          │  Write  │
                                         │ Engine  │          │  Side   │
                                         └─────────┘          └─────────┘
                                         semantic +           decisions,
                                         recency +            handoffs,
                                         confidence           notes

Your markdown notes are embedded with your configured provider (local or cloud) and stored in SQLite for semantic and keyword retrieval. When your AI tool starts a session, SAME surfaces relevant context automatically. Decisions get extracted. Handoffs get generated. The next session picks up where you left off.

No Ollama? No problem. SAME Lite runs with zero external dependencies. Keyword search via SQLite FTS5 powers all features. Install Ollama later and same reindex upgrades to semantic mode instantly.

Features

*Semantic mode requires embeddings; keyword fallback is automatic.

Knowledge Graph

Explore relationships in your vault with the graph command group:

same graph stats
same graph query --type note --node "notes/architecture.md" --depth 2
same graph path --from-type note --from "notes/architecture.md" --to-type file --to "internal/store/db.go"
same graph rebuild

Graph data is built from indexed notes and stays local in SQLite. _PRIVATE/ files remain excluded because they are never indexed. Markdown note links (for example notes/next.md) are connected as note-to-note edges, so you can traverse actual learning paths across your vault. same graph rebuild clears stale graph data and re-extracts relationships from your indexed notes. LLM graph extraction is off by default; enable it explicitly with SAME_GRAPH_LLM=local-only (local endpoints only) or SAME_GRAPH_LLM=on.

same web now surfaces graph highlights (node/edge density + top relationship types) and shows per-note knowledge connections directly in the note viewer, so you can inspect relationship paths without leaving the dashboard.

Web Dashboard

Browse and search your vault from a local web UI:

same web              # opens http://localhost:4078
same web --open       # auto-opens browser
same web --port 8080  # custom port

Features:

• Dashboard with vault statistics (notes, chunks, DB size, search mode)
• Full-text and semantic search with relevance scoring
• Browse all notes with filtering and sorting
• Note viewer with metadata (tags, domain, content type)
• Knowledge graph highlights per note
• Pinned notes overview
• Dark/light theme (auto-detects system preference)

Runs on 127.0.0.1 only — never exposed to the network. No external dependencies. Works with keyword search if Ollama is unavailable.

Seed Vaults

Pre-built knowledge vaults that give your AI expert-level context in one command.

same seed install claude-code-power-user

10 seeds available, including:

Plus: security-audit-framework, devops-runbooks, indie-hacker-playbook, open-source-launch-kit, freelancer-business-kit, home-chef-essentials, fitness-and-wellness.

Run same seed list for full details. Catalog updates independently from SAME releases.

Browse all seeds

MCP Tools

SAME exposes 12 tools via MCP for any compatible client.

Read

Write

Your AI can now write to its own memory, not just read from it. Decisions persist. Handoffs survive. Every session builds on the last.

Works With

SAME works with any directory of .md files. No Obsidian required.

Use same init --mcp-only to skip Claude Code hooks and just register the MCP server.

SAME vs. Alternatives

[1] BSL 1.1: Free for personal, educational, hobby, research, and evaluation use. Converts to Apache 2.0 on 2030-02-02.

Table reflects open-source versions as of February 2026. Verify current state before citing.

Privacy by Design

SAME creates a three-tier privacy structure:

Privacy is structural — filesystem-level, not policy-based. same init creates a .gitignore that enforces these boundaries automatically.

Security hardening: Path traversal blocked across all tools. Dot-directory writes blocked. Symlink escapes prevented. Error messages sanitized — no internal paths leak to AI. Config files written with owner-only permissions (0o600). Ollama URL validated to localhost-only. Prompt injection patterns scanned before context injection. Push protection available for multi-agent workflows.

Install

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

# npm (all platforms; downloads prebuilt binary)
npm install -g @sgx-labs/same

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

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

If blocked by execution policy, run first: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

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"  # add to ~/.zshrc to persist
same init --yes

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"
same init --yes

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

docker build -t same .
docker run --rm -v ~/my-notes:/vault same status
docker run --rm -v ~/my-notes:/vault same search "authentication"

# Bash
source <(same completion bash)

# Zsh
same completion zsh > "${fpath[1]}/_same"

# Fish
same completion fish | source

[vault]
path = "/home/user/notes"
# skip_dirs = [".venv", "build"]
# noise_paths = ["experiments/", "raw_outputs/"]
handoff_dir = "sessions"
decision_log = "decisions.md"

[ollama]
url = "http://localhost:11434"

[embedding]
provider = "ollama"           # "ollama" (default), "openai", "openai-compatible", or "none"
model = "nomic-embed-text"    # see supported models below
# api_key = ""                # required for openai, or set SAME_EMBED_API_KEY

[memory]
# presets: same profile use precise|balanced|broad|pi
max_token_budget = 800
max_results = 2
distance_threshold = 16.2
composite_threshold = 0.65

[hooks]
context_surfacing = true
decision_extractor = true
handoff_generator = true
feedback_loop = true
staleness_check = true

# Enable push protection
same guard settings set push-protect on

# Before pushing, explicitly allow it
same push-allow

# Check guard status
same guard status

FAQ

Do I need Obsidian? No. Any directory of .md files works.

Do I need Ollama? Recommended, not required. Semantic search understands meaning; without Ollama, SAME falls back to keyword search (FTS5). You can also use OpenAI embeddings (SAME_EMBED_PROVIDER=openai) or any OpenAI-compatible server like llama.cpp, VLLM, or LM Studio (SAME_EMBED_PROVIDER=openai-compatible). If your embedding server goes down temporarily, SAME falls back to keywords automatically.

Does it slow down my prompts? 50-200ms. Embedding is the bottleneck — search and scoring take <5ms.

Is my data sent anywhere? SAME is fully local. Context surfaced to your AI tool is sent to that tool's API as part of your conversation, same as pasting it manually.

How much disk space? 5-15MB for a few hundred notes.

What are seeds? Pre-built knowledge vaults. Install one and your AI has expert-level context immediately. same seed list to browse, same seed install <name> to install. All local, all free.

Can I use multiple vaults? Yes. same vault add work ~/work-notes && same vault default work. Search across all of them with same search --all "your query" or via the search_across_vaults MCP tool.

Community

Discord · GitHub Discussions · Report a Bug

Support

Buy me a coffee · GitHub Sponsors

Built with

Go · SQLite + sqlite-vec · Ollama / OpenAI

License

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