Stash MCP
Stash gives an agent long-term memory in PostgreSQL: entries are merged into facts, relations and patterns, served over MCP, started in Docker
- 770 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Writes and deletes entries in PostgreSQL: the `forget` tool erases memory and consolidation rewrites facts on its own
- Entry texts go to the model provider that builds vectors and summaries from them
- Listens on port 8080 with no token, so anyone who can reach the address gets access to memory
Install
- Works in
Manual install
git clone https://github.com/alash3al/stash.gitThen copy `.env.example` to `.env`, fill in the key and model address and run `docker compose up`: it starts PostgreSQL with `pgvector`, migrations and the MCP server with background consolidation.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Writes and deletes entries in PostgreSQL: the `forget` tool erases memory and consolidation rewrites facts on its own
- Entry texts go to the model provider that builds vectors and summaries from them
- Listens on port 8080 with no token, so anyone who can reach the address gets access to memory
This is third-party code. Review the repository files before installing.
What it does
Stash is a self-hosted MCP server written in Go that keeps an agent's memory across sessions. The agent calls `remember` to store an episode or a fact, `recall` to find something by meaning and `forget` to delete an entry. Texts become vectors and live in PostgreSQL with the `pgvector` extension. Memory is split into namespaces: `init` creates the starter `/self` namespace with capabilities, limits and preferences, and `create_namespace` adds more. Background consolidation runs nine stages and turns raw entries into structured knowledge: facts, relations between them, causal links, patterns, contradictions, goals, failure patterns and hypothesis checks. Each stage processes only what appeared since the previous run. Consolidation can be triggered with the `consolidate` tool or a CLI command. For inspection there are `query_facts`, `query_relationships`, `list_contradictions` and `list_causal_links`, and `resolve_contradiction` marks a dispute as settled. The server exposes MCP over SSE at `http://localhost:8080/sse`. The repository ships a `docker-compose.yml` that starts PostgreSQL with `pgvector`, applies migrations and launches the server together with consolidation. Vectors and summaries are built by a model through an OpenAI-compatible API: an embedding model and a reasoning model are required, both set in `.env`.
Who it is for. For developers who want an agent in Cursor, Claude Desktop, Windsurf or OpenCode to remember preferences and decisions between sessions and keep that memory on their own server.
Good fit when
- The agent asks the same questions about your stack and habits in every new session, and you want to record them once with `remember`
- You need memory with separate namespaces: one per project and one for the agent itself
- Entries should be merged into facts and conflicts between old and new decisions should be flagged
- Data must sit in your own PostgreSQL, and models can be attached through an OpenAI-compatible address, including a local Ollama
Not a fit when
- You have no Docker and cannot install PostgreSQL with the `pgvector` extension: the server does not run without a database
- You need memory without a model key and without local models: vectors and consolidation are built by a model over an API
- You want to keep knowledge in plain Markdown files that you edit by hand: Basic Memory fits better
- You want hosting with no upkeep: the cloud version at usestash.io was written separately and shares no code with this repository
Example request
Remember in Stash that this project runs on PostgreSQL 16 with no ORM, and remind me of it at the start of the next sessionMCP
- Transport
- sse
- Authentication
- not required
Environment variables
STASH_OPENAI_API_KEYrequired, secret- Key of a model provider with an OpenAI-compatible API for embeddings and consolidation; for Ollama any value works
STASH_OPENAI_BASE_URLrequired- API address of the model provider
STASH_EMBEDDING_MODELrequired- Embedding model, its dimension must match `STASH_VECTOR_DIM`
STASH_REASONER_MODELrequired- Model that extracts relations and writes summaries during consolidation
STASH_POSTGRES_DSNrequired, secret- Connection string for PostgreSQL with the `pgvector` extension
Limitations
- License is Apache-2.0. The latest release in the repository is v0.2.11, a pre-1.0 version.
- The vector size `STASH_VECTOR_DIM` must match the embedding model: 1536 for `text-embedding-3-small`, 768 for `nomic-embed-text`. The Ollama guide warns that the value is fixed at first start: changing it needs a clean volume or a new database.
- A fully local setup is described in `docs/LOCAL_OLLAMA.md` (`nomic-embed-text` and `qwen2.5:3b`), contributed by a third party and tested on Linux. The guide says small models are enough for development.
- The sample `docker-compose.yml` uses the database password `stash_dev_password`, and client configs point at the SSE address with no token. On a shared network the password and access to port 8080 must be locked down separately.
- The cloud version at usestash.io was, according to the author, written from scratch, and its feature set differs in both directions. The repository README also carries an advert for the Atlas Cloud service.
How to disable. Remove the `stash` entry from the client configuration: `~/.cursor/mcp.json` for Cursor, `claude_desktop_config.json` for Claude Desktop, `~/.codeium/windsurf/mcp_config.json` for Windsurf or `~/.config/opencode/config.json` for OpenCode. Then stop the Docker Compose stack. Memory lives in the `postgres_data` volume, and deleting it erases every entry.
FAQ
Which agents can connect to Stash?
Any client that supports MCP over SSE. The repository gives ready snippets for Cursor, Claude Desktop, OpenCode and Windsurf, all with the address `http://localhost:8080/sse`. There is no separate guide for Claude Code.
Can Stash run fully locally?
Yes, following `docs/LOCAL_OLLAMA.md`. Ollama runs on the host and Stash in Docker reaches it at `http://host.docker.internal:11434/v1`. In `.env` you set the models `nomic-embed-text` and `qwen2.5:3b` and the vector size `768`. The models must be pulled before the first start.
What does consolidation do and when does it run?
It turns episodes into facts, and facts into relations, causal links and patterns, looks for contradictions and tracks goals. There are nine stages, each taking only new data. In Docker Compose the server starts with the `--with-consolidation` flag, so consolidation runs in the background. To run it by hand use the `consolidate` tool or the command `docker compose exec stash /stash consolidate run`.
What is a namespace for?
It splits memory by purpose. The `init` tool creates the `/self` namespace for the agent's capabilities and preferences, and `create_namespace` adds others. The context tools `set_context`, `get_context` and `clear_context` require a namespace.
How does the cloud version differ from this repository?
The cloud at usestash.io is in a free beta, connects with a single MCP address and Google sign-in. According to the author it was written from scratch and shares no code with the open repository.
What should I do if `recall` returns nothing?
The guide says to call `init` first, then `remember`, and only then `recall`. Also check that `.env` holds a working key: without it embeddings are not built. Logs are read with `docker compose logs stash`.
Discussion
No questions or reviews yet.
Related
MCP serversA long-term memory MCP server for AI agents: facts fade along a forgetting curve and related records are compressed into a summary
A long-term memory system for AI agents: the agent stores experience and facts, then retrieves them through a built-in MCP server
Open infrastructure for agents that learn from experience: session traces, a knowledge base and skill packs via CLI, MCP and API
Self-hosted long-term memory for agents: semantic search, a knowledge graph and autonomous consolidation over MCP and a REST API
A long-term memory MCP server for agents: one Rust binary that runs offline and never calls a language model
A self-hosted MCP server for long-term agent memory: structured records, versioned rollback and a visual dashboard
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Stash (this entry) | no | not required | 770 | |
| Basic Memory | no | not required | 4,389 | keeps knowledge in plain Markdown files that both the human and the agent read and edit |
| MCP Memory Service | no | not required | 2,054 | memory in a local database with vector search, available over MCP and a REST API |
| OKF Agent Memory | no | not required | 844 | project memory in a git-native format, a single Go binary and BM25 search |
README in short
The repository front page opens with a slogan about agent memory, a quick Docker start and links to the getting-started guide and the local Ollama guide. Next come a block on connecting Atlas Cloud, ready MCP configs for Cursor, Claude Desktop, OpenCode and Windsurf, a description of the nine-stage consolidation and a note on the cloud version. The repository has a `docs` folder with two guides and a project page, database migrations, a `Dockerfile`, a sample `.env.example` and tests of the memory core in `internal/brain`.