{"id":43860769,"url":"https://github.com/sgx-labs/statelessagent","last_synced_at":"2026-04-01T19:00:10.673Z","repository":{"id":337527641,"uuid":"1151739294","full_name":"sgx-labs/statelessagent","owner":"sgx-labs","description":"Your AI forgets everything between sessions. SAME fixes that. Local-first, no API keys, single binary.","archived":false,"fork":false,"pushed_at":"2026-04-01T02:42:06.000Z","size":2669,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-01T03:58:08.956Z","etag":null,"topics":["ai-agent","ai-memory","claude-code","context-surfacing","cursor","golang","llm-memory","local-first","mcp","mcp-server","model-context-protocol","obsidian","rag","semantic-search","sqlite","sqlite-vec","vector-search","windsurf"],"latest_commit_sha":null,"homepage":"https://statelessagent.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sgx-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"buy_me_a_coffee":"sgxlabs","github":"sgx-labs"}},"created_at":"2026-02-06T20:53:41.000Z","updated_at":"2026-04-01T02:11:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sgx-labs/statelessagent","commit_stats":null,"previous_names":["sgx-labs/statelessagent"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/sgx-labs/statelessagent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgx-labs%2Fstatelessagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgx-labs%2Fstatelessagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgx-labs%2Fstatelessagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgx-labs%2Fstatelessagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sgx-labs","download_url":"https://codeload.github.com/sgx-labs/statelessagent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgx-labs%2Fstatelessagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-memory","claude-code","context-surfacing","cursor","golang","llm-memory","local-first","mcp","mcp-server","model-context-protocol","obsidian","rag","semantic-search","sqlite","sqlite-vec","vector-search","windsurf"],"created_at":"2026-02-06T10:13:37.831Z","updated_at":"2026-04-01T19:00:10.611Z","avatar_url":"https://github.com/sgx-labs.png","language":"Go","funding_links":["https://buymeacoffee.com/sgxlabs","https://github.com/sponsors/sgx-labs"],"categories":[],"sub_categories":[],"readme":"\u003c!-- mcp-name: io.github.sgx-labs/same --\u003e\n# SAME — Persistent Memory for AI Coding Agents\n\n[![License: BSL 1.1](https://img.shields.io/badge/License-BSL_1.1-blue.svg)](LICENSE)\n[![Go](https://img.shields.io/badge/Go-1.25+-00ADD8.svg)](https://go.dev)\n[![Latest Release](https://img.shields.io/github/v/release/sgx-labs/statelessagent)](https://github.com/sgx-labs/statelessagent/releases)\n[![GitHub Stars](https://img.shields.io/github/stars/sgx-labs/statelessagent)](https://github.com/sgx-labs/statelessagent)\n[![MCP Tools](https://img.shields.io/badge/MCP_Tools-19-8A2BE2.svg)](#mcp-server)\n[![Discord](https://img.shields.io/discord/1468523556076785757?color=5865F2\u0026label=Discord\u0026logo=discord\u0026logoColor=white)](https://discord.gg/9KfTkcGs7g)\n\n**Your AI forgets everything between sessions. SAME fixes that.**\n\nSAME 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.\n\nOne binary. Fully local. No cloud. No telemetry. Mac, Linux, Windows, Raspberry Pi.\n\n## Install\n\n```bash\n# macOS / Linux\ncurl -fsSL https://statelessagent.com/install.sh | bash\n\n# Windows (PowerShell)\nirm https://statelessagent.com/install.ps1 | iex\n```\n\nOr via npm (all platforms): `npm install -g @sgx-labs/same`\n\n**Installed via npm?** Update with `npx same@latest` or `npm update -g @sgx-labs/same`.\n\n## See It Work\n\n```bash\nsame demo\n```\n\n```\nIndexing 5 sample notes...\nSearching: \"authentication decision\"\n\n  1. decisions/auth-strategy.md (score: 0.94)\n     \"We chose JWT with refresh tokens for...\"\n\n  2. notes/api-security.md (score: 0.87)\n     \"Auth middleware validates tokens at...\"\n\nAsking: \"what did we decide about authentication?\"\n\n  Based on your notes, you decided to use JWT with refresh\n  tokens (decisions/auth-strategy.md). The API middleware\n  validates tokens at the gateway level (notes/api-security.md).\n\nNo accounts. No API keys. Everything runs locally.\n```\n\n## Quickstart\n\n```bash\n# 1. Point SAME at your project\ncd ~/my-project \u0026\u0026 same init\n\n# 2. Test search\nsame search \"authentication decision\"\n\n# 3. Done. Your AI now has memory.\n# Start Claude Code, Cursor, or any MCP client.\n```\n\n`same init` sets up hooks and MCP tools automatically. Your AI gets relevant context on every session start.\n\n## Key Features\n\n- **Your AI remembers everything** -- Decisions, handoffs, and context survive across sessions. Close your terminal, switch projects, come back tomorrow. Nothing gets lost.\n\n- **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.\n\n- **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.\n\n- **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.\n\n- **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.\n\n- **Safe for teams** -- Multiple AI agents on the same codebase won't step on each other. File claims, push protection, and attribution built in.\n\n- **Instant expertise** -- 17 pre-built knowledge vaults with 870+ curated notes. One command to install. Your AI gets domain knowledge in seconds.\n\n- **Connected knowledge** -- See how decisions, files, and notes relate to each other. Ask \"what depends on this?\" and get real answers. Powered by SQLite.\n\n## Security \u0026 Teams\n\nSAME includes built-in PII scanning and push protection:\n\n- **PII scanning** -- Pre-commit hooks detect emails, API keys, secrets, and personal data before they reach git. Configurable blocklists with false-positive review workflow.\n- **Push protection** -- Multi-agent file claims prevent AI agents from overwriting each other's work. Advisory locks with attribution.\n- **Audit logging** -- Every guard scan, every allow decision, every override is logged.\n- **Privacy tiers** -- `_PRIVATE/` is never indexed. `research/` is indexed but never committed. Your notes, your rules.\n\n```bash\nsame guard settings set push-protect on    # enable push protection\nsame guard scan                            # run PII scan manually\n```\n\n## How It Works\n\n```\nYour Notes (.md)  --\u003e  Embeddings  --\u003e  SQLite  --\u003e  Your AI Tool\n                       (local or        (search      (Claude Code,\n                        cloud)           + rank)      Cursor, etc.)\n```\n\nYour 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.\n\n**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.\n\n## Why SAME\n\n| Without SAME | With SAME |\n|-------------|-----------|\n| Re-explain everything each session | AI picks up where you left off |\n| \"Didn't we decide to use JWT?\" | Decision surfaces automatically |\n| \"Is this note still accurate?\" | Trust state flags stale knowledge |\n| Close terminal = context lost | Handoff recovers the session |\n| Copy-paste notes into chat | `same ask` with source citations |\n| Context compacted mid-task | Pinned notes survive compaction |\n\n## The Numbers\n\n| Metric | Value |\n|--------|-------|\n| Recall@5 | **100%** keyword, **84%** semantic on internal eval (68 cases). Held-out: **90%** Recall@5 on 30 blind cases (see `eval/METHODOLOGY.md`) |\n| MRR | **0.65** keyword, **0.62** semantic |\n| Prompt overhead | **\u003c200ms** |\n| Binary size | **~14MB** |\n| Setup time | **Under 2 minutes** |\n\n## Add to Your AI Tool\n\n### Claude Code (recommended)\n\n```bash\nsame init    # installs 6 hooks + MCP automatically\n```\n\n### Cursor / Windsurf / Any MCP Client\n\nAdd to your MCP config (`.mcp.json`, Cursor settings, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"same\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@sgx-labs/same\", \"mcp\", \"--vault\", \"/path/to/your/notes\"]\n    }\n  }\n}\n```\n\n19 MCP tools available instantly. Works without Ollama (keyword fallback).\n\nSwitch between Claude Code and Cursor without losing context. Your memory travels with you.\n\n### Tool Compatibility\n\n**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.\n\n## MCP Server\n\n| Tool | What it does |\n|------|-------------|\n| `search_notes` | Semantic search across your knowledge base |\n| `search_notes_filtered` | Search with domain/tag/agent filters |\n| `search_across_vaults` | Federated search across multiple vaults |\n| `get_note` | Read full note content by path |\n| `find_similar_notes` | Discover related notes |\n| `get_session_context` | Pinned notes + latest handoff + git state |\n| `recent_activity` | Recently modified notes |\n| `save_note` | Create or update a note |\n| `save_decision` | Log a structured project decision |\n| `create_handoff` | Write a session handoff |\n| `reindex` | Re-scan and re-index the vault |\n| `index_stats` | Index health and statistics |\n| `mem_consolidate` | Consolidate related notes via LLM |\n| `mem_brief` | Generate orientation briefing |\n| `mem_health` | Vault health with trust analysis |\n| `mem_forget` | Suppress a note from search results |\n| `mem_restore` | Undo mem_forget (unsuppress a note) |\n| `mem_list_suppressed` | List suppressed notes |\n| `save_kaizen` | Log improvement items with provenance |\n\n## SeedVaults\n\nPre-built knowledge vaults. One command to install.\n\n```bash\nsame seed list                              # browse available seeds\nsame seed install claude-code-power-user    # install one\n```\n\n| Seed | Notes | What you get |\n|------|:-----:|-------------|\n| `same-getting-started` | 18 | Learn SAME itself — the universal on-ramp |\n| `claude-code-power-user` | 50 | Claude Code workflows and operational patterns |\n| `ai-agent-architecture` | 56 | Agent design, orchestration, memory strategies |\n| `api-design-patterns` | 56 | REST, GraphQL, auth, rate limiting, and more |\n| `typescript-fullstack-patterns` | 55 | Full-stack TypeScript patterns and best practices |\n| `engineering-management-playbook` | 59 | Engineering leadership and team management |\n| `personal-productivity-os` | 117 | GTD, time blocking, habit systems |\n| `security-audit-framework` | 61 | Security review checklists and frameworks |\n\nPlus 9 more. [Browse all 17 seeds on GitHub.](https://github.com/sgx-labs/seed-vaults)\n\n## Privacy\n\nAll data stays on your machine. SAME creates a three-tier privacy structure:\n\n| Directory | Indexed | Committed | Use for |\n|-----------|:-------:|:---------:|---------|\n| Your notes | Yes | Your choice | Docs, decisions, research |\n| `_PRIVATE/` | No | No | API keys, credentials |\n| `research/` | Yes | No | Strategy, analysis |\n\nNo telemetry. No cloud. Path traversal blocked. Config files written with owner-only permissions.\n\n## More\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull CLI Reference\u003c/strong\u003e\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `same init` | Set up SAME for your project |\n| `same demo` | See SAME in action with sample notes |\n| `same tutorial` | 7 hands-on lessons |\n| `same ask \u003cquestion\u003e` | Ask a question, get cited answers |\n| `same search \u003cquery\u003e` | Search your notes |\n| `same search --all \u003cquery\u003e` | Search across all vaults |\n| `same status` | See what SAME is tracking |\n| `same doctor` | Run diagnostic checks |\n| `same claim \u003cpath\u003e --agent \u003cname\u003e` | Advisory file ownership for multi-agent |\n| `same pin \u003cpath\u003e` | Always include a note in sessions |\n| `same graph stats` | Knowledge graph diagnostics |\n| `same web` | Local web dashboard |\n| `same seed list` | Browse available seed vaults |\n| `same seed install \u003cname\u003e` | Install a seed vault |\n| `same vault list\\|add\\|remove\\|default` | Manage multiple vaults |\n| `same guard settings set push-protect on` | Enable push protection |\n| `same consolidate` | Merge related notes into knowledge summaries |\n| `same brief` | AI-generated orientation briefing |\n| `same health` | Vault health score with trust/provenance analysis |\n| `same stale` | List all stale notes in your vault |\n| `same search --trust stale` | Filter search by trust state |\n| `same search --type decision` | Filter search by content type |\n| `same ignore` | View/manage .sameignore patterns |\n| `same facts` | View, search, and manage extracted facts |\n| `same config set \u003ckey\u003e \u003cvalue\u003e` | Set config values from CLI |\n| `same brief --no-llm` | Structured briefing without LLM |\n| `same tips` | Best practices for vault hygiene and security |\n| `same reindex [--force]` | Rebuild search index |\n| `same repair` | Back up and rebuild database |\n| `same update` | Update to latest version |\n| `same completion [bash\\|zsh\\|fish]` | Shell completions |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eConfiguration\u003c/strong\u003e\u003c/summary\u003e\n\nSAME uses `.same/config.toml`, generated by `same init`:\n\n```toml\n[vault]\npath = \"/home/user/notes\"\nhandoff_dir = \"sessions\"\ndecision_log = \"decisions.md\"\n\n[embedding]\nprovider = \"ollama\"           # \"ollama\", \"openai\", \"openai-compatible\", or \"none\"\nmodel = \"nomic-embed-text\"\n\n[memory]\nmax_token_budget = 800\nmax_results = 2\n```\n\nSupported embedding models: `nomic-embed-text` (default), `snowflake-arctic-embed2`, `mxbai-embed-large`, `all-minilm`, `text-embedding-3-small` (OpenAI), and more.\n\nConfiguration priority (highest wins): CLI flags \u003e Environment variables \u003e Config file \u003e Defaults\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMore Install Options\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Docker\ngit clone --depth 1 https://github.com/sgx-labs/statelessagent.git\ncd statelessagent \u0026\u0026 docker build -t same .\n\n# Build from source (requires Go 1.25+)\ngit clone --depth 1 https://github.com/sgx-labs/statelessagent.git\ncd statelessagent \u0026\u0026 make install\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTroubleshooting\u003c/strong\u003e\u003c/summary\u003e\n\nStart with `same doctor` -- it runs 20+ checks and tells you what's wrong.\n\n**\"No vault found\"** -- Run `same init` from inside your notes folder, or set `VAULT_PATH=/path/to/notes`.\n\n**\"Ollama not responding\"** -- SAME falls back to keyword search automatically. Test with `curl http://localhost:11434/api/tags`.\n\n**Hooks not firing** -- Run `same setup hooks` to reinstall. Verify with `same status`.\n\n**Database issues** -- Run `same repair` to back up and rebuild.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSAME vs. Alternatives\u003c/strong\u003e\u003c/summary\u003e\n\n| | SAME | mem0 | Letta | CLAUDE.md |\n|---|:---:|:---:|:---:|:---:|\n| Setup | 1 command | pip + config | pip or Docker | Edit file |\n| Runtime deps | None | Python + vector DB | Python + SQLAlchemy | None |\n| Offline | Full | Not default | With local models | Yes |\n| Cloud required | No | Default yes | No | No |\n| Telemetry | None | Default ON | Yes | None |\n| MCP tools | 19 | 9 | Client only | No |\n| Memory integrity | Provenance + trust | No | No | No |\n| Knowledge graph | Built-in | Requires Neo4j | No | No |\n| Cross-tool memory | Yes | API only | No | Claude only |\n| Runs on Pi | Yes (~14MB) | No | No | Yes |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEval Methodology\u003c/strong\u003e\u003c/summary\u003e\n\nInternal evaluation on 105 tuning cases. Held-out validation: 93.3% Recall@5 on 30 blind test cases (see `eval/METHODOLOGY.md`).\n\n| Metric | Value | Dataset |\n|--------|-------|---------|\n| Recall@5 (keyword) | 100% | Internal (68 cases) |\n| Recall@5 (semantic) | 84% | Internal (68 cases) |\n| MRR (keyword) | 0.65 | Internal (68 cases) |\n| Recall@5 | 90% | Held-out (30 blind cases) |\n\nAll evaluation uses synthetic vault data. No user data used.\n\n\u003c/details\u003e\n\n## Links\n\n- [Website](https://statelessagent.com)\n- [Telegram Bot Plugin](https://github.com/sgx-labs/same-telegram)\n- [SeedVaults](https://github.com/sgx-labs/seed-vaults)\n- [Discord](https://discord.gg/9KfTkcGs7g)\n- [Changelog](CHANGELOG.md)\n\n## Contributing\n\nContributions welcome. [Open an issue](https://github.com/sgx-labs/statelessagent/issues) or start a [discussion](https://github.com/sgx-labs/statelessagent/discussions).\n\n```bash\ngit clone https://github.com/sgx-labs/statelessagent.git\ncd statelessagent\nmake build \u0026\u0026 make test\n```\n\nSee [SECURITY.md](SECURITY.md) for security-related reports.\n\n## Support\n\n[Buy me a coffee](https://buymeacoffee.com/sgxlabs) | [GitHub Sponsors](https://github.com/sponsors/sgx-labs)\n\n## License\n\nBSL 1.1. Free for personal, educational, hobby, research, and evaluation use. Converts to Apache 2.0 on 2030-02-02. See [LICENSE](LICENSE).\n\n---\n\n\u003ca href=\"https://glama.ai/mcp/servers/@sgx-labs/statelessagent\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@sgx-labs/statelessagent/badge\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgx-labs%2Fstatelessagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsgx-labs%2Fstatelessagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgx-labs%2Fstatelessagent/lists"}