Stash — Unified Memory Engine for AI Agents
https://usestash.io

Stash gives AI agents one persistent memory URL per account over MCP (Model Context
Protocol). Agents connect to a single URL and get a shared, searchable memory that
works across all tools and conversations — Claude Code, Cursor, OpenCode, Replit,
Claude Desktop, and any other MCP-compatible tool.

Think of it as a cloud whiteboard for all your agents: every tool can read from it
and write to it. Context, rules, lessons, and project notes — written once, recalled
everywhere, automatically.


QUICK SETUP

Claude Code
  claude mcp add --transport http stash https://usestash.io/mcp/{your-token}

OpenCode — add to opencode.json
  {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
      "stash": { "type": "remote", "url": "https://usestash.io/mcp/{your-token}", "enabled": true }
    }
  }

Cursor — add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
  {
    "mcpServers": {
      "stash": { "url": "https://usestash.io/mcp/{your-token}" }
    }
  }

Replit
  Integrations > Add custom MCP server
  Display name: Stash
  MCP Server URL: https://usestash.io/mcp/{your-token}

Claude Desktop
  Settings > Connectors > Add custom connector
  MCP URL: https://usestash.io/mcp/{your-token}

Get your token at: https://usestash.io/app


MCP TOOLS

init
  Call first in every conversation. Returns connection status, plan title, monthly
  embedding token usage and limits, namespace count, and memory entry count.
  Optional: pass context (one-line task description) to get the most relevant
  memories returned immediately without a separate grep call.
  Optional: context_limit (default 5, max 10) controls how many memories are returned.

mkns
  Create a namespace and all missing parent segments.
  Required: path (e.g. /rules or /projects/weather-app)
  Required: about (description of what the namespace stores — must be non-empty)
  Optional: visibility (private or public, default private)
  Does not consume embedding tokens.

write
  Store a memory entry in an existing namespace. Namespace must exist first (call mkns).
  Required: content
  Optional: path (defaults to /)
  Embeds content via BGE-M3 and returns entry UUID, tokens used, and created_at.
  If similar entries already exist in the same namespace (cosine distance < 0.15),
  they are returned as similar_existing so you can remove outdated ones.

batch_write
  Store up to 50 memory entries into one existing namespace in a single call.
  All entries are embedded in one API request and inserted in one transaction.
  Required: path, contents (array of strings, 1–50 items)
  Returns a UUID per entry and total tokens used.

update
  Replace the content of an existing memory entry and re-embed it.
  Soft-deletes the old entry and inserts a new one — all in one transaction.
  Required: entry_uuid, content
  Returns old_entry_uuid, new_entry_uuid, and tokens used.

grep
  Semantic vector search across memory entries using cosine similarity.
  Required: query
  Optional: path (scope to a namespace subtree)
  Optional: limit (default 10, max 50)
  Optional: max_age_days (exclude entries older than N days; 0 = no filter)
  Results include age_days. Consumes embedding tokens for the query.

ls
  List direct child namespaces and memory entries of a namespace path.
  Cursor-based pagination (cursor + limit params, default 50, max 200).
  Optional: path (defaults to /)
  Does not consume embedding tokens.

dump
  Return all memory entries under a namespace subtree, grouped by namespace.
  Up to 10 entries per namespace, 200 entries total. Truncated namespaces are marked.
  Required: path
  Does not consume embedding tokens.

tree
  Return the full namespace hierarchy under a path as a lightweight nested tree
  (path, about, children). No entries included. No embedding cost.
  Use for structural orientation at the start of a session.
  Required: path

recent
  Return the N most recently written memory entries, ordered newest first.
  Optional: path (scope to a namespace subtree)
  Optional: limit (default 20, max 100)
  Does not consume embedding tokens.

get
  Retrieve a single memory entry by UUID.
  Returns content, namespace_path, age_days, and created_at.
  Required: entry_uuid
  Does not consume embedding tokens.

rm
  Soft-delete a memory entry by UUID or an entire namespace subtree.
  Required: kind (memory or namespace)
  Required when kind=memory: entry_uuid
  Required when kind=namespace: path
  Root namespace "/" cannot be removed. Does not consume embedding tokens.


NAMESPACES

Namespaces are hierarchical paths (like a filesystem). Examples:
  /rules              standing instructions and constraints
  /lessons            mistakes made, things that failed, hard-won insights
  /preferences        communication style, tool choices, personal preferences
  /goals              short and long-term goals
  /projects/myapp     context, decisions, notes for a specific project
  /people/alice       notes about a collaborator

Namespaces must be created with mkns before writing to them.
Slugs are case-insensitive. Soft deletes — nothing is permanently removed.


AGENT PROTOCOL

1. Call init at the start of every conversation. Pass a context string describing
   the current task to get relevant memories immediately.
2. Use grep before answering any non-trivial question.
3. Write immediately when you learn anything worth keeping — do not wait or ask.
4. Use meaningful namespace paths. One distinct idea per entry.
5. Use update or rm to correct stale or wrong memories.


PLANS AND QUOTAS

Free plan: 50,000 embedding tokens per month, 0 reasoning tokens.
Quota is checked before every embedding operation. Exceeding quota returns an error.
Usage resets monthly.