Snail.MCP.Memory

๐Ÿ“– Docs & site: orldev.github.io/Snail.MCP.Memory โ€” this README and the tool reference in docs/, built by docs.yml

Long-term memory for your AI agent. Connect this MCP server to Claude Code, Claude Desktop, VS Code or any other MCP client โ€” and the agent starts remembering your decisions, lessons and preferences between sessions, across projects, in your language.

What changes for you once it is connected:

  • You clear the chat, come back tomorrow โ€” the agent recalls what was decided and why.
  • You start a new project โ€” the agent recognizes "I have seen a project like this" and briefs itself with the lessons and decisions from similar past work, so old mistakes are not repeated.
  • You ask "what problems did we have with X?" โ€” the answer comes from meaning, not keywords: memory is searched with a multilingual embedding model, a question in Russian finds a lesson recorded in English and vice versa.
  • Memory keeps itself clean: near-duplicates are refused, short-lived events expire, stale records are nominated for deletion โ€” but nothing durable is ever deleted without your confirmation.

Everything runs on your machine: a single SQLite file and an in-process embedding model by default, no accounts, no cloud, no API keys. When you outgrow one machine, the same server speaks PostgreSQL.

Quick start

1. Install (needs the .NET 10 SDK):

dotnet tool install --global Snail.MCP.Memory --prerelease

This gives you the s3l-mcp-memory command (~/.dotnet/tools must be on PATH โ€” the .NET installer puts it there). Update later with dotnet tool update --global Snail.MCP.Memory --prerelease.

Alternative, no install: the SDK ships the dnx runner โ€” dnx Snail.MCP.Memory --yes --prerelease fetches the package from NuGet on first use, caches it and runs it.

2. Connect it to your client under the name mem0 (details per client below):

claude mcp add mem0 --scope user -- s3l-mcp-memory

3. Use it. In your next session say something like:

init memory for this project โ€” we are building a REST API in Go with PostgreSQL

The agent calls init_project_memory, and if your memory already knows similar projects, the reply includes a briefing: which past projects look alike and what lessons they carry. From then on the agent saves decisions and lessons as you work and recalls them when they matter.

On the very first semantically-searched call the server downloads the embedding model (~123 MB, once, into ~/.s3l-mcp-memory/models/). Until it arrives โ€” and on machines where it never can โ€” everything still works, with text search instead of semantic search.

Connecting to a client

The server is a stdio MCP server: every client config boils down to "run the server command" โ€” s3l-mcp-memory (the global tool), or dnx Snail.MCP.Memory --yes --prerelease to skip installation. The examples below register it as mem0; the name is yours to choose, but the slash commands in this repo pre-approve tools under mem0. Zero configuration is required โ€” settings only change the defaults.

Claude Code

claude mcp add mem0 --scope user -- s3l-mcp-memory

Or in .mcp.json at the project root:

{
  "mcpServers": {
    "mem0": {
      "command": "s3l-mcp-memory"
    }
  }
}

Running through dnx instead: "command": "dnx", "args": ["Snail.MCP.Memory", "--yes", "--prerelease"].

Claude Desktop

Config file: macOS โ€” ~/Library/Application Support/Claude/claude_desktop_config.json, Windows โ€” %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "mem0": {
      "command": "s3l-mcp-memory"
    }
  }
}

If the client cannot find the command, use the full path: /Users/<you>/.dotnet/tools/s3l-mcp-memory (with dnx โ€” its full path next to dotnet).

VS Code

.vscode/mcp.json:

{
  "servers": {
    "mem0": {
      "type": "stdio",
      "command": "s3l-mcp-memory"
    }
  }
}

Every setting in one config

All settings are optional environment variables. This example lists all of them with their default values โ€” copy it and keep only the lines you change:

{
  "mcpServers": {
    "mem0": {
      "command": "s3l-mcp-memory",
      "env": {
        "SNAIL_MCP_MEMORY_PROVIDER": "Sqlite",
        "SNAIL_MCP_MEMORY_DIRECTORY": "~/.s3l-mcp-memory",
        "SNAIL_MCP_MEMORY_CONNECTION_STRING": "",
        "SNAIL_MCP_MEMORY_WORKSPACE": "",
        "SNAIL_MCP_MEMORY_EMBEDDING_ENABLED": "true",
        "SNAIL_MCP_MEMORY_EMBEDDING_MODEL_PATH": "~/.s3l-mcp-memory/models/model.onnx",
        "SNAIL_MCP_MEMORY_EMBEDDING_TOKENIZER_PATH": "~/.s3l-mcp-memory/models/sentencepiece.bpe.model",
        "SNAIL_MCP_MEMORY_EMBEDDING_MODEL_URL": "https://huggingface.co/Xenova/multilingual-e5-small/resolve/main/onnx/model_quantized.onnx",
        "SNAIL_MCP_MEMORY_EMBEDDING_TOKENIZER_URL": "https://huggingface.co/intfloat/multilingual-e5-small/resolve/main/sentencepiece.bpe.model",
        "SNAIL_MCP_MEMORY_EMBEDDING_DIMENSIONS": "384",
        "SNAIL_MCP_MEMORY_EMBEDDING_IDLE_MINUTES": "30",
        "SNAIL_MCP_MEMORY_DUPLICATE_THRESHOLD": "0.95",
        "SNAIL_MCP_MEMORY_SIMILARITY_FLOOR": "0.75",
        "SNAIL_MCP_MEMORY_IDLE_TIMEOUT_MINUTES": "60",
        "SNAIL_MCP_MEMORY_AUDIT_INTERVAL_DAYS": "7"
      }
    }
  }
}

The same keys can live in the settings file instead, ~/.config/s3l-mcp-memory/config.json, with bare names inside. It is found by the one chain of every Snail server (Snail.Sdk's ServerSettings): a file named in SNAIL_MCP_MEMORY_CONFIG is the only one read, and when it is missing no file is; otherwise the first that exists of ./.s3l-mcp-memory.json, ./s3l-mcp-memory.json, ~/.config/s3l-mcp-memory/config.json, ~/.s3l-mcp-memory.json:

{
  "Provider": "Sqlite",
  "Workspace": "backend",
  "SimilarityFloor": "0.8"
}

Environment variables win over the file. A secret โ€” a PostgreSQL connection string with its password โ€” belongs in the settings file (chmod 600 ~/.config/s3l-mcp-memory/config.json), never in a client's registration or a launchd job: those travel wherever they are copied.

What each setting means

Setting Default Meaning
PROVIDER Sqlite Storage backend: Sqlite (single local file, sqlite-vec) or Postgres (server database, pgvector)
DIRECTORY ~/.s3l-mcp-memory Where the database and the models live; understands a leading ~
CONNECTION_STRING โ€” SQLite: a file path or Data Source=... (default {Directory}/memory.db). PostgreSQL: the full connection string, required
WORKSPACE (empty) Partition of a shared database: your writes are tagged with it, your reads see only it. Empty โ€” the whole base. See Sharing one database
EMBEDDING_ENABLED true false turns semantic search off; records are stored without vectors and recall falls back to text matching
EMBEDDING_MODEL_PATH {Directory}/models/model.onnx Where the ONNX model lives; downloaded on first use
EMBEDDING_TOKENIZER_PATH {Directory}/models/sentencepiece.bpe.model Where the SentencePiece tokenizer lives; downloaded on first use
EMBEDDING_MODEL_URL / EMBEDDING_TOKENIZER_URL multilingual-e5-small Where the files are downloaded from when missing
EMBEDDING_DIMENSIONS 384 Vector length of the configured model โ€” change only together with the model
EMBEDDING_IDLE_MINUTES 30 Minutes without an embedding before the model is released from memory; the next embedding loads it again (~0.4 s). 0 keeps it loaded for good
DUPLICATE_THRESHOLD 0.95 Similarity above which remember refuses a near-duplicate and offers to supersede the old record instead
SIMILARITY_FLOOR 0.75 Similarity below which a search hit is dropped. Raise to ~0.8 if recall feels noisy, lower if it misses things
TRANSPORT Stdio Http runs one server for every session of the machine โ€” see One server for every session
URL http://127.0.0.1:9230 Where the HTTP server listens, on loopback only: the endpoint has no key, so an address beyond loopback (0.0.0.0 among them), LISTENS_ON_EVERY_INTERFACE=true or a start inside a container is refused at the start, naming the variable
PORT โ€” A port alone also means HTTP: the server listens on that port of URL's host
IDLE_TIMEOUT_MINUTES 60 Minutes without any MCP message before an orphaned stdio server process shuts itself down; 0 is the default hour, it cannot be turned off. A server over HTTP is never stopped
AUDIT_INTERVAL_DAYS 7 Days between background audit runs; 0 disables the audit

What the agent can do with it

You normally never call these yourself โ€” the agent does, guided by the tool descriptions and by the memory rules you wire in (see Integration). Knowing them helps you phrase requests.

Tool What it does
init_project_memory registers a project and returns the experience briefing; without a name, uses the folder the client was started in; description finds similar past projects, seedFrom preloads named donors
remember stores one typed record โ€” fact, decision, lesson, preference, reference, task, event, note; refuses a near-duplicate (supersede with replaceId, keep both with force); links creates graph edges in the same call
recall semantic search; empty project โ€” the whole memory (that is how experience crosses projects), empty query โ€” an overview of the newest records
forget deletes records by id, several ids comma-separated
review_memory nominates stale records for deletion; the deletion itself stays a confirmed forget
list_projects the projects that have memory, optionally narrowed by a name prefix
rename_project renames a project everywhere: registry, records, edges
forget_project forgets a whole project โ€” records, edges, link suggestions, registration โ€” in two calls: without confirm it only counts what would go, with confirm: true it deletes
link_projects a directed, typed edge between projects: uses, depends_on, design_of, part_of, implements, documents
unlink_projects removes the edges of a project pair
dismiss_link rejects a pending link suggestion so the pair is never proposed again
sync_project_links upserts machine-extracted relations (from a manifest, an Obsidian vault, an XML registry, โ€ฆ) as auto edges that never overwrite manual ones
get_graph the edges around a project, depth 1โ€“5, without loading records

Symmetric "these are related" links are deliberately not stored: vector similarity derives them at query time.

What a tool answers

Every tool answers in the envelope every Snail server answers in: one JSON text block, {"ok":true,"data":โ€ฆ} on success, {"ok":false,"error":โ€ฆ,"hint":โ€ฆ,"type":โ€ฆ} on a refusal, which is also flagged isError. A record carries its id in full โ€” what forget and replaceId take back โ€” and leaves out what it does not hold; an answer that found nothing says which nothing in note. A recall of a project:

{"ok":true,"data":{"project":"Snail.MCP.Memory","search":"overview","records":[{"id":"4abbb314-08df-42f3-b3c5-e1ac580aa601","kind":"fact","project":"Snail.MCP.Memory","content":"the stack is .NET","updated":"2026-11-08"}]}}

and a remember refused because a very similar record exists, with that record as data:

{"ok":false,"error":"Not stored: a very similar record already exists (similarity 0.97).","hint":"pass replaceId with its id to supersede it, or force: true to store both","type":"duplicate","data":{"id":"4abbb314-โ€ฆ","kind":"fact","project":"Snail.MCP.Memory","content":"the stack is .NET","updated":"2026-11-08","similarity":0.97}}

The refusal kinds are emptyName, unresolvedName, notFound, nameTaken, invalidId, duplicate, selfLink and unknownLinkType; a call whose arguments do not fit the tool is arguments, and a failure inside the server internal. Until 0.5 the tools answered Markdown text; a script that read it reads data now.

A record that mentions a known project with no edge to its own queues a pending link suggestion. A mention is the project's name as a whole word; a name of one or two letters (UI) is never matched, nor the user folder of a home path (/Users/<name>/, /home/<name>/). The queue returns with every project-scoped recall and with init_project_memory until each pair is resolved: link_projects confirms the relation, dismiss_link rejects it permanently โ€” there is no third state, so conceptual relations named in conversation stop getting lost.

A background audit completes the picture: once per interval (AUDIT_INTERVAL_DAYS, default 7, 0 disables) the server re-scans all records and queues suggestions the write-time scan could not see โ€” for example a mention written before the mentioned project had memory. However many agents share one database, the audit runs once per interval: every server process wakes hourly, and the run goes to whichever first claims an atomic lease stored in the database.

Integration: copy two things from this repo

The protocol carries the tool descriptions โ€” enough for basic use. The full integration is two files you copy yourself from git into your agent's setup; nothing is installed automatically:

  1. Slash commands โ€” .claude/commands/ holds mem0-init, mem0-recall, mem0-remember, mem0-link, mem0-graph, mem0-list: manual one-shot shortcuts with the mem0 tools pre-approved (allowed-tools), so they run without permission prompts. Copy them into ~/.claude/commands/ (globally) or <project>/.claude/commands/:
cp .claude/commands/mem0-*.md ~/.claude/commands/

If you registered the server under a name other than mem0, adjust the mcp__mem0__ prefix inside the files to match.

  1. Memory rules for the agent โ€” server-instructions.md is the full instruction set: the kind vocabulary, when to save without being asked, when to search before proposing, how to self-heal wrong records. Paste its content into your agent's instruction file โ€” ~/.claude/CLAUDE.md for Claude Code, the system prompt of a custom agent, or wherever your client keeps standing instructions. The agent works without it, but with it the memory maintains itself: the rules are what turns the tools into a habit.

One server for every session

Over stdio every Claude session starts a server of its own โ€” the runtime, the embedding model and a database connection each time, ~115 MB per session. With TRANSPORT=Http one server answers them all: five sessions measured 136 MB together, and a new session is answered in 12 ms instead of ~160.

On macOS launchd keeps it running. Publishing with -p:SnailMcpInstall=true writes the job, with this machine's paths, to ~/.s3l-mcp/Snail.MCP.Memory/s3l.mcp.memory.plist (from deploy/) and restarts it when it is loaded. Loading it is done once:

cp ~/.s3l-mcp/Snail.MCP.Memory/s3l.mcp.memory.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/s3l.mcp.memory.plist
claude mcp add -s user --transport http mem0 http://127.0.0.1:9230/mcp

Settings other than the transport go into ~/.config/s3l-mcp-memory/config.json. init_project_memory without a name asks the client for the folder it works in (MCP roots), since the server's own folder is nobody's project. The endpoint has no key: it listens on loopback and nowhere else โ€” a URL beyond loopback, LISTENS_ON_EVERY_INTERFACE=true or a start inside a container is refused at the start, naming the variable โ€” and refuses any request that carries an Origin, which every browser page sends and no agent client does. GET /healthz answers 200 while the server is up.

A client may be given some of the tools by the address it opens its session at: http://127.0.0.1:9230/mcp?tool=recall&tool=remember lists those two alone and refuses any other as notGranted โ€” an agent that may read and write the memory but never forget or forget_project. An address that names no tool is given them all.

Sharing one database

Two situations, two mechanisms:

  • Several projects, one person โ€” nothing to configure. Projects live side by side in one database; that is what makes cross-project experience transfer work.
  • Several people (or separate directions of work), one database โ€” give each their own WORKSPACE. Everything a server writes is tagged with its workspace and its reads never leave it, so teammates do not see each other's memory. A server with an empty workspace reads the whole base โ€” useful for an overview across all of them.

PostgreSQL

For a shared or backed-up memory, point the server at PostgreSQL with the pgvector extension available (the pgvector/pgvector Docker images ship it). The connection string carries a password, so it goes into ~/.config/s3l-mcp-memory/config.json (chmod 600):

{
  "Provider": "Postgres",
  "ConnectionString": "Host=db.example.com;Database=memory;Username=snail;Password=..."
}

Nothing else changes โ€” same tools, same behavior, tables and vector indexes are created on first use.

Good to know

  • Language: record content is stored in the language of your conversation; the embedding model is multilingual, so search works across languages.
  • Offline: after the one-time model download the server needs no network at all.
  • Lifecycle: event records expire after 90 days; durable kinds are only ever deleted by an explicit, confirmed forget, and a whole project by a confirmed forget_project.
  • Housekeeping: an orphaned stdio server process shuts itself down after an hour without an MCP message (IDLE_TIMEOUT_MINUTES), never in the middle of a background audit.
  • Memory when idle: the embedding model is most of what the server holds; after half an hour without an embedding it is released (~150 MB back, 321 โ†’ 173 MB measured), and the next semantic call loads it again in ~0.4 s (EMBEDDING_IDLE_MINUTES). The server logs both on stderr.
  • Your data is yours: one SQLite file at ~/.s3l-mcp-memory/memory.db, inspectable with any SQLite browser.

Development

dotnet test          # SQLite suite; PostgreSQL contract tests run when a Docker daemon is reachable (Testcontainers, pgvector image)
dotnet pack src -c Release -o out

Published from the repository beside the other Snail MCP servers, it lives in ~/.s3l-mcp/Snail.MCP.Memory, and current follows every later publication. It stays framework-dependent: Entity Framework and the ONNX runtime keep it from being a native program.

dotnet publish src -c Release -p:SnailMcpInstall=true
claude mcp add -s user mem0 -e SNAIL_MCP_MEMORY_PROVIDER=Sqlite -e SNAIL_MCP_MEMORY_DIRECTORY=~/.csharp-tools-memory -- dotnet ~/.s3l-mcp/Snail.MCP.Memory/current/Snail.MCP.Memory.dll