SAME MCP Server provides persistent memory for your AI tools by bridging your Markdown notes with a local, private memory store. It exposes a set of MCP endpoints that let your AI assistants read, write, and surface context from your notes across sessions, without relying on cloud services or external APIs.

How to use

You use SAME by connecting an MCP client to its local server. Start by initializing a vault that points SAME at your Markdown notes, then interact with your AI tool as usual. When you begin a new session, SAME surfaces relevant notes, extracts decisions, and generates handoffs so your next session picks up where you left off. You can search your notes, ask questions with citations, and pin critical context to remain present in every session.

Typical workflow with an MCP client is: initialize the vault, perform queries or prompts through the MCP interface, and let SAME provide persistent memory across sessions. You can run the same toolset across Claude Code, Cursor, Windsurf, or any MCP client, and SAME will surface context automatically.

How to install

Prerequisites: you need a working environment with either curl or npm available, and Go for building from source if you choose that path.

Install SAME using one of the supported methods. Choose a direct binary install, or install via npm.

Direct binary install (macOS / Linux):

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

same demo

Install via npm (any platform):

npm install -g @sgx-labs/same

Windows PowerShell install (requires execution policy adjustment if blocked):

ir statelessagent.com/install.ps1 | iex

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Manual install (or have your AI assist you):

# macOS (Apple Silicon)
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"  # persist in your shell config
same init --yes

# macOS (Intel) build from source or use Rosetta
arch -arm64 ./same-darwin-arm64

# Linux (x86_64)
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

# Build from source (any platform)
git clone --depth 1 https://github.com/sgx-labs/statelessagent.git
cd statelessagent && make install
same init --yes

Requires Go 1.25+ and CGO.

## MCP configuration and usage

The MCP setup connects your local SAME server with your AI client. You can enable hooks and MCP support in one step, or register the MCP server manually in your client’s configuration.

Example MCP configuration (manual): you can configure the MCP server entry to point to SAME using the embedded command and arguments shown here.

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

## Configuration and behavior

SAME uses a configuration file at .same/config.toml that you generate with same init. This file controls vault path, Ollama usage, embedding provider, memory thresholds, and hooks for surface context, decision extraction, and handoff generation.

Key configuration values include your vault path, embedding provider and model, and memory management settings. You can adjust which notes surface in prompts, how many results you retrieve, and how decisions and handoffs are stored.

Example configuration (TOML):

[vault] path = "/home/user/notes" handoff_dir = "sessions" decision_log = "decisions.md"

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

[embedding] provider = "ollama" model = "nomic-embed-text"

api_key = "" # required for openai provider

[memory] 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

## Security and privacy

SAME is designed to keep your data on your machine. You control how notes are indexed and surfaced, with explicit boundaries to protect sensitive directories. The system blocks path traversal, prevents writes to dot-directories, and sanitizes error messages to avoid leaking internal paths.

Important privacy boundaries include a three-tier structure for indexing and committing notes, with a private area for credentials and API keys. You can disable indexing of certain directories and constrain notes that are surfaced in prompts.

## Troubleshooting

If you encounter issues, start by verifying the MCP connection and vault setup. Check that the same client context surfaces notes and that the MCP server is reachable on the expected port.

Common fixes include reinitializing the hooks, rebuilding the index, or repairing the local database.

Quick diagnostics include running the built-in doctor tool to perform checks across configurations, vaults, and surface mechanisms.

## Tools and endpoints

SAME exposes a set of MCP endpoints that cover reading and writing memory. These endpoints allow you to search your notes, read full note content, find related notes, manage session context, and write decisions and handoffs.

## Available tools

### search\_notes

Semantic search across your knowledge base.

### search\_notes\_filtered

Search with domain/workstream/tag filters.

### search\_across\_vaults

Federated search across multiple 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.

### reindex

Re-scan and re-index the vault.

### index\_stats

Index health and statistics.

### save\_note

Create or update a markdown note (auto-indexed).

### save\_decision

Log a structured project decision.

### create\_handoff

Write a session handoff for the next session.