# Stash

Stash is a persistent memory layer for AI agents — Go single binary, Postgres + pgvector backend, MCP server, model-agnostic. The pitch: episodes (raw observations) get synthesized in the background into facts, relationships, causal links, patterns, and contradictions, organized under hierarchical namespaces. Same problem as [[hippo-memory]] and [[mempalace]], different philosophy: stash leans hardest on the consolidation pipeline.

Listed on [[toolbox/watchlist]] — repo created 2026-04-24, one day before this entry. Three v0.x releases shipped in the first 24 hours. The author (Mohammed Al Ashaal) is established (247 public repos, 557 followers), but the project itself is brand new.

## The nine-stage consolidation pipeline

This is the most distinctive part of Stash. A background process runs on a schedule and walks raw observations up an abstraction ladder:

| # | Stage | What it does |
|---|---|---|
| 01 | Episodes | Append-only log of raw observations as they happen |
| 02 | Facts | LLM clusters related episodes into synthesized beliefs with confidence |
| 03 | Relationships | Entity edges extracted from facts (knowledge graph) |
| 04 | Causal Links | Cause-effect pairs between facts |
| 05 | Patterns | Higher-order abstractions across multiple facts |
| 06 | Contradictions | Self-correction and confidence decay when beliefs conflict |
| 07 | Goal Inference (NEW) | Facts auto-tracked against active goals; progress and contradictions surfaced |
| 08 | Failure Patterns (NEW) | Detect repeated mistakes; extract failure patterns as new facts |
| 09 | Hypothesis Scan (NEW) | New evidence passively confirms or rejects open hypotheses |

[[hippo-memory]] also has a consolidation step (`hippo sleep` merges episodic memories into semantic patterns) but stops at stage 5. Stash extends the same biological-memory metaphor into causal reasoning, contradiction handling, and goal/hypothesis tracking. Whether stages 4–9 actually work as advertised is the open question — these are the kind of claims that need real-world reps to verify, and a one-day-old repo doesn't have those reps.

## Hierarchical namespaces

Memory is organized like a filesystem. Paths are hierarchical, reads recurse into subtrees, writes always target one exact path:

```
/                       (everything)
├── /users/alice        (who alice is, her preferences)
├── /projects           (all projects)
│   ├── /projects/restaurant-saas
│   └── /projects/mobile-app
└── /self               (agent self-knowledge)
    ├── /self/capabilities
    ├── /self/limits
    └── /self/preferences
```

The `/self` namespace is the unusual part. Calling `init` scaffolds it, and the agent uses its own memory layer to maintain a self-model — what it does well, where it struggles, how it prefers to operate. This is closer to autonomous-research-agent design than typical "save user preferences" memory. Compare to [[charlie-daemons]] (markdown-defined autonomous AI processes) and the broader [[agents-vs-daemons]] distinction — Stash sits more on the daemon end if the `/self` loop is taken seriously.

## Stash vs. RAG

The landing page makes a long argument that Stash is not a [[rag-limitations|RAG]] system. RAG retrieves over documents you already wrote; Stash creates knowledge from what the agent experiences. The framing is "librarian" vs. "colleague." Practically, this means Stash is consuming structured tool-call traces and conversation turns, not pre-existing corpora — and producing structured facts/relationships/hypotheses, not chunks. Both can coexist in a stack: RAG for documents, Stash for experience.

## MCP integration

Speaks MCP natively. 28 tools covering `remember`/`recall`/`forget`, namespace management, fact queries, relationship traversal, causal-chain queries, contradiction resolution, hypothesis management, and the consolidation trigger. Two commands to wire it into Claude Desktop, Cursor, OpenCode, or any MCP client:

```bash
./stash mcp execute --with-consolidation
./stash mcp serve --port 8080 --with-consolidation
```

## Model-agnostic backend

Stash uses one OpenAI-compatible provider for both embedding and reasoning. The `.env` config points at OpenRouter, Ollama, vLLM, Groq, LM Studio, or any compliant endpoint. The author runs Stash locally pointed at OpenRouter:

```bash
STASH_OPENAI_BASE_URL=https://openrouter.ai/api/v1
STASH_OPENAI_API_KEY=sk-or-...
STASH_EMBEDDING_MODEL=openai/text-embedding-3-small
STASH_REASONER_MODEL=anthropic/claude-3-haiku
STASH_VECTOR_DIM=1536
```

`STASH_VECTOR_DIM` is locked at first init — pgvector dimensions can't change without a database reset. The default is 1536 (OpenAI `text-embedding-3-small`); Ollama with `nomic-embed-text` is 768.

## Setup

Three commands via Docker Compose, which wires Postgres + pgvector + Stash + MCP server + the consolidation worker together:

```bash
git clone https://github.com/alash3al/stash
cd stash
cp .env.example .env   # set API key, models, STASH_VECTOR_DIM
docker compose up
```

## Autonomous loop

Stash ships an autonomous-research loop intended to be run as a cron job — every 5 minutes the agent orients (recalls context, goals, failures), researches a topic of its own choosing, surfaces tensions in what it now knows, generates a hypothesis or pattern, runs the consolidation pipeline, writes a session summary, and stops. This is the most aggressive interpretation of agent memory in the toolbox so far. Whether it produces useful learning or just thrashes is unproven.

## Status

- Created: 2026-04-24
- Stars: 96 (at time of ingest, 2026-04-25)
- Releases: v0.1.0, v0.1.1, v0.2.0 — all on 2026-04-25
- Open issues: 0, forks: 0
- Single author (`alash3al`)
- Author profile: established Go developer, Hurghada, Egypt, 247 public repos, 557 followers
- Apache-2.0

Re-check signals at 2026-07-25: do stages 4–9 (causal links, contradictions, goals, failures, hypotheses) actually produce useful output in real use? Has anyone besides the author shipped a non-trivial integration? Has the API stabilized? Did the star trajectory continue or flat-line?

**Repo:** https://github.com/alash3al/stash — 96 stars, Apache-2.0.