Skip to main content
Glama
Stateless Agent Memory Engine (SAME)

Stateless Agent Memory Engine (SAME)

by sgx-labs

SAME — Persistent Memory for AI Coding Agents

License: BSL 1.1 Go Latest Release GitHub Stars MCP Tools Discord

Your AI forgets everything between sessions. SAME fixes that.

SAME gives every AI coding tool persistent memory. Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI — one memory layer that works everywhere. It indexes your markdown notes, surfaces relevant context automatically, and records decisions and handoffs so your AI picks up where it left off.

One binary. Fully local. No cloud. No telemetry. Mac, Linux, Windows, Raspberry Pi.

Install

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

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

Or via npm (all platforms): npm install -g @sgx-labs/same

Installed via npm? Update with npx same@latest or npm update -g @sgx-labs/same.

Related MCP server: Nowledge Mem

See It Work

same demo
Indexing 5 sample notes...
Searching: "authentication decision"

  1. decisions/auth-strategy.md (score: 0.94)
     "We chose JWT with refresh tokens for..."

  2. notes/api-security.md (score: 0.87)
     "Auth middleware validates tokens at..."

Asking: "what did we decide about authentication?"

  Based on your notes, you decided to use JWT with refresh
  tokens (decisions/auth-strategy.md). The API middleware
  validates tokens at the gateway level (notes/api-security.md).

No accounts. No API keys. Everything runs locally.

Quickstart

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

# 2. Test search
same search "authentication decision"

# 3. Done. Your AI now has memory.
# Start Claude Code, Cursor, or any MCP client.

same init sets up hooks and MCP tools automatically. Your AI gets relevant context on every session start.

Key Features

  • Your AI remembers everything -- Decisions, handoffs, and context survive across sessions. Close your terminal, switch projects, come back tomorrow. Nothing gets lost.

  • Memory integrity -- Tracks provenance (where notes came from), detects when source files change, and flags stale knowledge. Stale notes rank lower in search automatically. same health shows trust state across your vault.

  • Dual-layer memory -- Extracts atomic facts from your notes via LLM. Facts are independently searchable and boost source notes in search results. The right answer surfaces even when the fact is buried in an unrelated conversation.

  • Streamable HTTP transport -- same web --mcp enables an HTTP MCP endpoint with Bearer token auth. Connect from Open WebUI, LobeChat, or any HTTP MCP client — no stdio required.

  • Works with your tools -- 19 MCP tools for Claude Code, Cursor, Windsurf, or any MCP client. Search, save decisions, create handoffs without leaving your editor.

  • Safe for teams -- Multiple AI agents on the same codebase won't step on each other. File claims, push protection, and attribution built in.

  • Instant expertise -- 17 pre-built knowledge vaults with 870+ curated notes. One command to install. Your AI gets domain knowledge in seconds.

  • Connected knowledge -- See how decisions, files, and notes relate to each other. Ask "what depends on this?" and get real answers. Powered by SQLite.

Security & Teams

SAME includes built-in PII scanning and push protection:

  • PII scanning -- Pre-commit hooks detect emails, API keys, secrets, and personal data before they reach git. Configurable blocklists with false-positive review workflow.

  • Push protection -- Multi-agent file claims prevent AI agents from overwriting each other's work. Advisory locks with attribution.

  • Audit logging -- Every guard scan, every allow decision, every override is logged.

  • Privacy tiers -- _PRIVATE/ is never indexed. research/ is indexed but never committed. Your notes, your rules.

same guard settings set push-protect on    # enable push protection
same guard scan                            # run PII scan manually

How It Works

Your Notes (.md)  -->  Embeddings  -->  SQLite  -->  Your AI Tool
                       (local or        (search      (Claude Code,
                        cloud)           + rank)      Cursor, etc.)

Your markdown notes get embedded and stored in SQLite. When your AI starts a session, SAME surfaces relevant context via hooks or MCP. Decisions get extracted. Handoffs get generated. The next session picks up where the last one stopped.

No Ollama? No problem. SAME runs with zero external dependencies using keyword search (SQLite FTS5). Add Ollama later for semantic search -- same reindex upgrades instantly.

Why SAME

Without SAME

With SAME

Re-explain everything each session

AI picks up where you left off

"Didn't we decide to use JWT?"

Decision surfaces automatically

"Is this note still accurate?"

Trust state flags stale knowledge

Close terminal = context lost

Handoff recovers the session

Copy-paste notes into chat

same ask with source citations

Context compacted mid-task

Pinned notes survive compaction

The Numbers

Metric

Value

Recall@5

100% keyword, 84% semantic on internal eval (68 cases). Held-out: 90% Recall@5 on 30 blind cases (see eval/METHODOLOGY.md)

MRR

0.65 keyword, 0.62 semantic

Prompt overhead

<200ms

Binary size

~14MB

Setup time

Under 2 minutes

Add to Your AI Tool

same init    # installs 6 hooks + MCP automatically

Cursor / Windsurf / Any MCP Client

Add to your MCP config (.mcp.json, Cursor settings, etc.):

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

19 MCP tools available instantly. Works without Ollama (keyword fallback).

Switch between Claude Code and Cursor without losing context. Your memory travels with you.

Tool Compatibility

Claude Code gets full automatic handoffs via hooks. Cursor, Windsurf, Codex CLI, Gemini CLI get full MCP tool access (search, save, decisions, graph) but handoffs need to be triggered manually. We're working on automatic handoff support for more editors.

MCP Server

Tool

What it does

search_notes

Semantic search across your knowledge base

search_notes_filtered

Search with domain/tag/agent filters

search_across_vaults

Federated search across multiple vaults

get_note

Read full note content by path

find_similar_notes

Discover related notes

get_session_context

Pinned notes + latest handoff + git state

recent_activity

Recently modified notes

save_note

Create or update a note

save_decision

Log a structured project decision

create_handoff

Write a session handoff

reindex

Re-scan and re-index the vault

index_stats

Index health and statistics

mem_consolidate

Consolidate related notes via LLM

mem_brief

Generate orientation briefing

mem_health

Vault health with trust analysis

mem_forget

Suppress a note from search results

mem_restore

Undo mem_forget (unsuppress a note)

mem_list_suppressed

List suppressed notes

save_kaizen

Log improvement items with provenance

SeedVaults

Pre-built knowledge vaults. One command to install.

same seed list                              # browse available seeds
same seed install claude-code-power-user    # install one

Seed

Notes

What you get

same-getting-started

18

Learn SAME itself — the universal on-ramp

claude-code-power-user

50

Claude Code workflows and operational patterns

ai-agent-architecture

56

Agent design, orchestration, memory strategies

api-design-patterns

56

REST, GraphQL, auth, rate limiting, and more

typescript-fullstack-patterns

55

Full-stack TypeScript patterns and best practices

engineering-management-playbook

59

Engineering leadership and team management

personal-productivity-os

117

GTD, time blocking, habit systems

security-audit-framework

61

Security review checklists and frameworks

Plus 9 more. Browse all 17 seeds on GitHub.

Privacy

All data stays on your machine. SAME creates a three-tier privacy structure:

Directory

Indexed

Committed

Use for

Your notes

Yes

Your choice

Docs, decisions, research

_PRIVATE/

No

No

API keys, credentials

research/

Yes

No

Strategy, analysis

No telemetry. No cloud. Path traversal blocked. Config files written with owner-only permissions.

More

Command

Description

same init

Set up SAME for your project

same demo

See SAME in action with sample notes

same tutorial

7 hands-on lessons

same ask <question>

Ask a question, get cited answers

same search <query>

Search your notes

same search --all <query>

Search across all vaults

same status

See what SAME is tracking

same doctor

Run diagnostic checks

same claim <path> --agent <name>

Advisory file ownership for multi-agent

same pin <path>

Always include a note in sessions

same graph stats

Knowledge graph diagnostics

same web

Local web dashboard

same seed list

Browse available seed vaults

same seed install <name>

Install a seed vault

same vault list|add|remove|default

Manage multiple vaults

same guard settings set push-protect on

Enable push protection

same consolidate

Merge related notes into knowledge summaries

same brief

AI-generated orientation briefing

same health

Vault health score with trust/provenance analysis

same stale

List all stale notes in your vault

same search --trust stale

Filter search by trust state

same search --type decision

Filter search by content type

same ignore

View/manage .sameignore patterns

same facts

View, search, and manage extracted facts

same config set <key> <value>

Set config values from CLI

same brief --no-llm

Structured briefing without LLM

same tips

Best practices for vault hygiene and security

same reindex [--force]

Rebuild search index

same repair

Back up and rebuild database

same update

Update to latest version

same completion [bash|zsh|fish]

Shell completions

SAME uses .same/config.toml, generated by same init:

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

[embedding]
provider = "ollama"           # "ollama", "openai", "openai-compatible", or "none"
model = "nomic-embed-text"

[memory]
max_token_budget = 800
max_results = 2

Supported embedding models: nomic-embed-text (default), snowflake-arctic-embed2, mxbai-embed-large, all-minilm, text-embedding-3-small (OpenAI), and more.

Configuration priority (highest wins): CLI flags > Environment variables > Config file > Defaults

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

# Build from source (requires Go 1.25+)
git clone --depth 1 https://github.com/sgx-labs/statelessagent.git
cd statelessagent && make install

Start with same doctor -- it runs 20+ checks and tells you what's wrong.

"No vault found" -- Run same init from inside your notes folder, or set VAULT_PATH=/path/to/notes.

"Ollama not responding" -- SAME falls back to keyword search automatically. Test with curl http://localhost:11434/api/tags.

Hooks not firing -- Run same setup hooks to reinstall. Verify with same status.

Database issues -- Run same repair to back up and rebuild.

SAME

mem0

Letta

CLAUDE.md

Setup

1 command

pip + config

pip or Docker

Edit file

Runtime deps

None

Python + vector DB

Python + SQLAlchemy

None

Offline

Full

Not default

With local models

Yes

Cloud required

No

Default yes

No

No

Telemetry

None

Default ON

Yes

None

MCP tools

19

9

Client only

No

Memory integrity

Provenance + trust

No

No

No

Knowledge graph

Built-in

Requires Neo4j

No

No

Cross-tool memory

Yes

API only

No

Claude only

Runs on Pi

Yes (~14MB)

No

No

Yes

Internal evaluation on 105 tuning cases. Held-out validation: 93.3% Recall@5 on 30 blind test cases (see eval/METHODOLOGY.md).

Metric

Value

Dataset

Recall@5 (keyword)

100%

Internal (68 cases)

Recall@5 (semantic)

84%

Internal (68 cases)

MRR (keyword)

0.65

Internal (68 cases)

Recall@5

90%

Held-out (30 blind cases)

All evaluation uses synthetic vault data. No user data used.

Contributing

Contributions welcome. Open an issue or start a discussion.

git clone https://github.com/sgx-labs/statelessagent.git
cd statelessagent
make build && make test

See SECURITY.md for security-related reports.

Support

Buy me a coffee | GitHub Sponsors

License

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


Available Tools

17 tools
create_handoffA
Idempotent

Create a session handoff note so the next session picks up where this one left off. Write what you worked on, what's pending, and any blockers.

Args: summary: What was accomplished this session pending: What's left to do (optional) blockers: Any blockers or open questions (optional) agent: Optional writer attribution stored in frontmatter (e.g. 'codex')

Returns path to the handoff note.

Inputs: summary (required), pending, blockers, agent.

find_similar_notesA
Read-only

Find notes that cover similar topics to a given note. Use this to discover related context, find notes that might conflict, or build a broader picture of a topic.

Args: path: Relative path of the source note top_k: Number of similar notes (default 5, max 100)

Returns list of related notes ranked by similarity.

Inputs: path (required), top_k (required).

get_noteA
Read-only

Read the full content of a note. Use this after search_notes returns a relevant result and you need the complete text. Paths are relative to the vault root.

Args: path: Relative path from vault root (as returned by search_notes)

Returns full markdown text content.

Inputs: path (required).

get_session_contextA
Read-only

Get orientation context for a new session. Returns pinned notes, the latest handoff, and recent decisions — everything you need to pick up where the last session left off.

Returns structured session context.

index_statsA
Read-only

Check the health and size of the note index. Use this to verify the index is up to date or to report stats to the user.

Returns note count, chunk count, last indexed timestamp, embedding model info, and database size.

If the user reports problems, suggest they run same doctor for diagnostics. For bugs, direct them to: https://github.com/sgx-labs/statelessagent/issues

mem_briefA
Read-only

Get an orientation briefing of what matters right now. Shows recent activity, open decisions, and key context. Use this at the start of a session to understand current project state.

Args: max_items: Maximum items per section (default 5)

Returns a concise briefing generated from vault contents. (experimental)

Inputs: max_items (required).

mem_consolidateA
Destructive

Consolidate related notes in the vault. Merges duplicates, resolves contradictions, extracts key facts. Creates new knowledge files without modifying originals. Use this when the vault has many similar or overlapping notes.

Args: dry_run: Preview what would be consolidated without writing files (default false) threshold: Similarity threshold for grouping notes, 0.0-1.0 (default 0.75)

Returns consolidation summary with groups found, facts extracted, and conflicts resolved. (experimental)

Inputs: dry_run (required), threshold (required).

mem_forgetA
Idempotent

Suppress a memory so it won't be surfaced in normal search. The note is not deleted -- it's marked as suppressed and will only appear if explicitly requested. Use this for outdated, incorrect, or irrelevant memories. This is not easily reversible: there is no mem_restore tool.

Args: path: Path of the note to suppress (required) reason: Why this memory is being suppressed (optional)

Returns confirmation of suppression. (experimental)

Inputs: path (required), reason.

mem_healthA
Read-only

Check the health of the memory vault. Returns a health score (0-100) and actionable recommendations. Use this to determine if the vault needs consolidation, reindexing, or cleanup.

Returns health score, key metrics, and recommendations. (experimental)

recent_activityA
Read-only

Get recently modified notes. Use this to see what's changed recently or to orient yourself at the start of a session.

Args: limit: Number of recent notes (default 10, max 50)

Returns list of recently modified notes with titles and paths.

Inputs: limit (required).

reindexA
Destructive

Re-scan and re-index all markdown notes. Use this if the user has added or changed notes and search results seem stale. Incremental by default (only re-embeds changed files).

Args: force: Re-embed all files regardless of changes (default false)

Returns indexing statistics.

Inputs: force (required).

save_decisionA
Idempotent

Log a project decision. Appends to the decision log so future sessions can find it.

Args: title: Short decision title (e.g. 'Use JWT for auth') body: Full decision details — what was decided, why, alternatives considered status: Decision status — 'accepted', 'proposed', or 'superseded' (default 'accepted') agent: Optional writer attribution stored in frontmatter (e.g. 'codex')

Returns confirmation.

Inputs: title (required), body (required), status (required), agent.

save_kaizenA
Idempotent

Log a friction point, bug, or improvement idea discovered during work. SAME tracks provenance — if the source files change later, the item is automatically flagged as potentially addressed.

Args: description: What was observed (required) area: Area of the codebase (e.g. 'indexer', 'config', 'hooks') (optional) agent: Who observed it (optional) sources: Related file paths for provenance tracking (optional)

Returns confirmation with the file path.

Inputs: description (required), area, agent, sources.

save_noteA
Destructive

Create or update a markdown note in the vault. The note is written to disk and indexed automatically.

Optionally specify source files to enable provenance tracking — SAME will flag this note as stale if sources change.

Args: path: Relative path within the vault (e.g. 'decisions/auth-approach.md') content: Markdown content to write append: If true, append to existing file instead of overwriting (default false) agent: Optional writer attribution stored in frontmatter (e.g. 'codex') sources: File paths that this note was derived from (optional)

Returns confirmation with the saved path.

Inputs: path (required), content (required), append (required), agent, +1 more.

search_across_vaultsA
Read-only

Search across multiple registered vaults at once. Use this instead of search_notes when you need context from other projects or want a cross-project view. Vaults must be registered first via the CLI (same vault add <name> <path>).

Args: query: Natural language search query top_k: Number of results (default 10, max 100) vaults: Comma-separated vault aliases to search. Omit to search all registered vaults. Unknown aliases are silently skipped.

Returns ranked results with titles, paths, snippets, and source vault name.

Inputs: query (required), top_k (required), vaults.

search_notesA
Read-only

Search the user's knowledge base for relevant notes, decisions, and context. Use this when you need background on a topic, want to find prior decisions, or need to understand project architecture.

Args: query: Natural language search query (e.g. 'authentication approach', 'database schema decisions') top_k: Number of results (default 10, max 100)

Returns ranked list of matching notes with titles, paths, and text snippets.

Inputs: query (required), top_k (required).

search_notes_filteredA
Read-only

Search the user's knowledge base with metadata filters. Use this when you want to narrow results by domain (e.g. 'engineering'), workstream (e.g. 'api-redesign'), tags, agent attribution, trust state, or content type.

Args: query: Natural language search query top_k: Number of results (default 10, max 100) domain: Filter by domain (e.g. 'engineering', 'product') workstream: Filter by workstream/project name tags: Comma-separated tags to filter by agent: Filter by agent attribution (e.g. 'codex', 'claude') trust_state: Filter by trust state (validated, stale, contradicted, unknown) content_type: Filter by content type (decision, handoff, note, research)

Returns filtered ranked list.

Inputs: query (required), top_k (required), domain, workstream, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 17 tools

    Disambiguation3/5

    There is significant overlap between search_notes, search_notes_filtered, and search_across_vaults—all perform search with varying scopes or filters, which could confuse agents about which to use. Similarly, mem_brief and get_session_context both provide session orientation, though mem_brief is experimental. Other tools like save_note and get_note have clear distinct purposes for write and read operations.

    Naming Consistency3/5

    Naming is mixed: some tools use verb_noun (e.g., create_handoff, save_note, search_notes), while others use noun_verb or other patterns (e.g., index_stats, mem_brief, recent_activity). This inconsistency makes the set less predictable, though most names are still readable and descriptive of their functions.

    Tool Count4/5

    With 17 tools, the count is on the higher side but reasonable for a memory engine covering note management, search, indexing, and session handling. It includes core operations like create, read, update, and search, plus experimental features, which fits the domain without being overly bloated.

    Completeness4/5

    The toolset covers key aspects of a memory engine: note CRUD (save_note, get_note), search (multiple variants), indexing (reindex, index_stats), session management (create_handoff, get_session_context), and experimental consolidation/health tools. A minor gap is the lack of a tool to update or delete notes directly (only suppression via mem_forget), but agents can work around this with save_note and append or overwrite.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers