Stash — 给 AI 装上持久记忆

Stash 项目封面图

图1：Stash 项目封面（来源：GitHub 仓库 docs/og-image.png）

痛点故事：AI 为何总是“失忆”？

想象这样一个场景：你花了一整周时间调试一个 AI 编程助手，告诉它你的代码库结构、技术栈偏好、项目的坑窟之处——第二天再问它，它完全“失忆”了，从零开始。这种“每次对话都是新生儿”的问题，是所有 LLM 应用的根本痛点。

Stash 正是来解决这个问题的。 它的 slogan 简洁有力 — “Your AI has amnesia. We fixed it.”（你的 AI 有忑忘症，我们治好了）。这是一个专门为 AI Agent 设计的长程记忆层，让 Agent 能够跨越会话记住关键信息，不再重复解释上下文。

背景：单 Agent 记忆需求的爆发

随着 AI Agent 框架（LangGraph、AutoGen、CrewAI 等）的成熟，开发者开始构建越来越复杂的自主 Agent 系统。但这些框架普遍缺乏一个关键能力：持久化记忆。上下文窗口（context window）再大，也装不下数周乃至数年的对话历史和知识积累。

Stash 由开发者 alash3al 于 2026 年 4 月创建，依托 Go 语言的高性能和简洁生态，快速获得了 713 颗星（截至 2026 年 6 月），展现出 AI 基础设施领域对记忆层解决方案的强烈需求。

项目核心定位：作为 AI Agent 的 MCP 协议记忆插件，无缝接入 Cursor、Claude Desktop、OpenCode、Windsurf 等主流开发工具，开箱即用，无需改动现有 Agent 代码。

核心架构：三层记忆模型

Stash 的记忆系统不是简单的对话日志存储，而是一套精心设计的三层记忆模型，模仿人类记忆的工作方式：

1. Episode（事件层）—— 原始感知

Agent 通过 MCP 工具 remember 存入的每一条信息，存储为一条不可变的 Episode，类似人类的即时记忆。Episode 包含：

content：原始文本内容
embedding：由 OpenAI（或 Ollama）生成的向量嵌入，用于语义检索
occurred_at：事件发生时间
namespace_id：命名空间归属，支持多 Agent 隔离记忆

Episode 是 append-only（只追加，不修改），保证了审计追溯性。

2. Fact（事实层）—— 结构化认知

定期运行的 Consolidation（记忆常规）管道，将一批 Episode 合成 Fact。Fact 是 LLM 合成的结构化事实，包含：

entity / property / value：三元组形式（如“pgxpool → database → PostgreSQL”）
confidence：置信度分数（0-1）
valid_from / valid_until：事实有效期
summary：LLM 生成的综合摘要

3. 高阶结构—— 因果与规律

在 Fact 之上，Stash 进一步提取：

Relationship：实体关系边
CausalLink：因果链（A 导致 B）
Pattern：跨事实的抽象模式
Hypothesis：带置信度的假设 + 验证计划
Goal / Failure：目标追踪和失败模式检测

这种多层抽象让 Agent 不仅能检索“说了什么”，更能理解“意味着什么”。

Consolidation 管道：8 阶段记忆常规引擎

internal/brain/consolidate.go 是整个项目最复杂的模块（20996 字节），实现了一个 8 阶段的增量常规管道：

阶段	输入	输出	LLM 调用
1. Episodes→Facts	一批 Episode	结构化 Fact + 矛盾检测	是
2. Facts→Relationships	Fact 列表	实体关系三元组	是
3. Facts→CausalLinks	Fact 对	因果边	是
4. Goal Progress	Goals + 新 Fact	目标完成度评估	是
5. Failure Patterns	Failures + Episodes	重复失败模式	是
6. Patterns	Facts + Relationships	高阶抽象模式	是
7. Hypothesis Evidence	Hypothesis + 新 Fact	假设确认/否定	是
8. Confidence Decay	全量 Fact	衰减后的置信度	否（纯 SQL）

后台每 5 分钟（可配置）自动运行，支持增量 checkpoint，崩溃恢复友好。Consolidation 核心逻辑由 LLM（gpt-4o-mini 或本地 Ollama）驱动。

关键设计：记忆衰减机制（Decay）——Fact 的置信度会随时间自然衰减（默认衰减因子 0.95），低于阈值自动过期删除，模仿人类记忆的遗忘曲线，避免数据库膨胀。

MCP Server：零代码接入任何 Agent

Stash 提供了完整的 MCP（Model Context Protocol）Server 实现，通过 SSE（Server-Sent Events）协议暴露以下工具：

MCP 工具	功能
`init`	创建 /self 命名空间（Agent 自我描述）
`remember`	存入 Episode
`recall`	语义向量检索相关记忆
`consolidate`	手动触发记忆常规管道
`facts`	查询结构化事实
`goal`	创建/追踪目标
`failure`	记录失败事件（用于失败模式分析）
`hypothesis`	提出假设并自动验证
`namespace`	多 Agent 记忆隔离
`forget`	软删除记忆

接入方式极为简单：在 Cursor、Claude Desktop、Windsurf 等工具的 MCP 配置文件中添加一行 URL 即可，无需修改任何 Agent 代码。

技术栈：Go + PostgreSQL/pgvector 的精打经算

为何是 Go？

单二进制部署：CGO_ENABLED=0 静态编译，distroless/static 镜像仅 ~15MB，无运行时依赖
pgx 连接池：25 max conns / 5 min conns，远优于 Python ORM 的慷连接模式
goroutine 并发：Consolidation 多阶段管道可高效并行处理大批量 Episode

数据库层关键设计（internal/db/db.go）：

使用 pgvector-go 扩展存储向量嵌入，维度锁定机制防止 Embedding 模型切换导致维度不匹配
HNSW 索引（Hierarchical Navigable Small World）创建完全幂等，重复运行不报错
goose 嵌入式 SQL migration，支持自动版本升级
启动时检查 settings 表，防止配置错误导致向量存储失败

Embedder 接口设计（internal/embedder/）：

抽象 Embedder 接口，支持 OpenAI（text-embedding-3-small / 3-large）和 Ollama（nomic-embed-text）两种后端
向量缓存（internal/embedder/cache.go）避免重复 Embedding 计算
向量维度自适应：OpenAI 1536维 vs Ollama 768维，通过 STASH_VECTOR_DIM 环境变量统一控制

部署体验：3 分钟从零到记忆可用

一键启动（最推荐的本地方式）：

git clone https://github.com/alash3al/stash.git
cd stash
cp .env.example .env   # 填入你的 OpenAI API Key
docker compose up

自动完成：Postgres 16（含 pgvector）初始化 → 20 个 SQL Migration → HNSW 索引创建 → MCP Server 启动。不需要手动建库、不需要安装 psql 客户端、不需要配置任何连接参数。

纯本地模式（零 API Key）： 使用 Ollama 替代 OpenAI API，向量维数改为 768：

# host: 运行 Ollama
ollama pull nomic-embed-text
ollama pull qwen2.5:3b
# .env: 切换到 Ollama 配置块
STASH_OPENAI_BASE_URL=http://host.docker.internal:11434/v1
STASH_EMBEDDING_MODEL=nomic-embed-text
STASH_REASONER_MODEL=qwen2.5:3b
STASH_VECTOR_DIM=768
docker compose up

局限与争议

1. LLM 成本不可忽视

Consolidation 管道每运行一次，对每个 Fact 都调用 LLM 推理。在高密度对话场景下（如每日处理 500+ Episode），OpenAI API 成本会快速累积。文档建议开发阶段用 Ollama（免费），生产环境切换到云端模型——但这需要开发者在两个配置间维护切换逻辑。

2. 向量维度锁定陷阱

STASH_VECTOR_DIM 在首次启动时锁定到 settings 表，之后修改不会自动迁移。切换维度需要重置数据库或重建，对已在生产环境运行的团队是一个潜在风险点。

3. Namespace 层级深度有限

Namespace slug 路径支持 / 分隔的层级，但代码中用正则 [a-z0-9][a-z0-9_-]{0,63} 限制单个层级段最大 64 字符，复杂多租户场景下可能遇到扩展瓶颈。

4. MCP Server 的 SSE 局限

当前 MCP 实现基于 SSE（Server-Sent Events），而非更现代的 WebSocket 双向通信。在高并发多 Agent 场景下，SSE 的单向拉模式可能造成工具调用排队延迟。

行业意义：从“上下文窗口竞赛”到“记忆基础设施”

2025 年以来，主流 LLM 厂商在上下文窗口上不断加码（Gemini 1.5 128K → Claude 200K → 1M token），但这种“堆窗口”方案并不能真正解决 Agent 的长程记忆问题：窗口再大，也装不下跨月跨年的知识积累，且成本随上下文长度线性增长。

Stash 代表了一种更优雅的路线：外部化记忆。记忆不放在 LLM 内部，而是存储在专用数据库中，按需语义检索注入上下文。这与人类大脑的工作方式更接近——不是记住所有细节，而是建立索引，按需提取。

Stash 的异化点在于：Go 单二进制 + MCP 协议 + 完整 Consolidation 管道，三者结合在开源社区中尚无直接对手。

快速上手路径

1. docker compose up（3分钟）
2. Cursor ~/.cursor/mcp.json 添加 {"url": "http://localhost:8080/sse"}
3. 对话中：call stash init → remember → recall → consolidate
4. 观察 facts 表中 LLM 合成的结构化知识

适用场景优先级：

⭐⭐⭐ 个人开发者/小团队：用 Cursor/Claude 写代码，需要 Agent 记住项目上下文
⭐⭐⭐ 多 Agent 协作：不同 Agent 通过 namespace 隔离记忆，避免互相干扰
⭐⭐ 客服/对话 Agent：需要跨会话记住用户偏好和历史互动
⭐ 研究原型：测试记忆增强对 Agent 任务完成率的影响

数据来源：GitHub alash3al/stash（Stars 713, Fork 35, Apache-2.0 License），分析基于 2026-06-17 最新提交，代码总量约 60 个 Go 文件，核心模块在 internal/brain/（记忆引擎）和 cmd/cli/（CLI + MCP Server）。

Stash — 给 AI 装上持久记忆

Stash 项目封面图

图1：Stash 项目封面（来源：GitHub 仓库 docs/og-image.png）

痛点故事：AI 为何总是“失忆”？

背景：单 Agent 记忆需求的爆发

核心架构：三层记忆模型

Stash 的记忆系统不是简单的对话日志存储，而是一套精心设计的三层记忆模型，模仿人类记忆的工作方式：

1. Episode（事件层）—— 原始感知

Agent 通过 MCP 工具 remember 存入的每一条信息，存储为一条不可变的 Episode，类似人类的即时记忆。Episode 包含：

content：原始文本内容
embedding：由 OpenAI（或 Ollama）生成的向量嵌入，用于语义检索
occurred_at：事件发生时间
namespace_id：命名空间归属，支持多 Agent 隔离记忆

Episode 是 append-only（只追加，不修改），保证了审计追溯性。

2. Fact（事实层）—— 结构化认知

定期运行的 Consolidation（记忆常规）管道，将一批 Episode 合成 Fact。Fact 是 LLM 合成的结构化事实，包含：

entity / property / value：三元组形式（如“pgxpool → database → PostgreSQL”）
confidence：置信度分数（0-1）
valid_from / valid_until：事实有效期
summary：LLM 生成的综合摘要

3. 高阶结构—— 因果与规律

在 Fact 之上，Stash 进一步提取：

Relationship：实体关系边
CausalLink：因果链（A 导致 B）
Pattern：跨事实的抽象模式
Hypothesis：带置信度的假设 + 验证计划
Goal / Failure：目标追踪和失败模式检测

这种多层抽象让 Agent 不仅能检索“说了什么”，更能理解“意味着什么”。

Consolidation 管道：8 阶段记忆常规引擎

internal/brain/consolidate.go 是整个项目最复杂的模块（20996 字节），实现了一个 8 阶段的增量常规管道：

阶段	输入	输出	LLM 调用
1. Episodes→Facts	一批 Episode	结构化 Fact + 矛盾检测	是
2. Facts→Relationships	Fact 列表	实体关系三元组	是
3. Facts→CausalLinks	Fact 对	因果边	是
4. Goal Progress	Goals + 新 Fact	目标完成度评估	是
5. Failure Patterns	Failures + Episodes	重复失败模式	是
6. Patterns	Facts + Relationships	高阶抽象模式	是
7. Hypothesis Evidence	Hypothesis + 新 Fact	假设确认/否定	是
8. Confidence Decay	全量 Fact	衰减后的置信度	否（纯 SQL）

后台每 5 分钟（可配置）自动运行，支持增量 checkpoint，崩溃恢复友好。Consolidation 核心逻辑由 LLM（gpt-4o-mini 或本地 Ollama）驱动。

MCP Server：零代码接入任何 Agent

Stash 提供了完整的 MCP（Model Context Protocol）Server 实现，通过 SSE（Server-Sent Events）协议暴露以下工具：

MCP 工具	功能
`init`	创建 /self 命名空间（Agent 自我描述）
`remember`	存入 Episode
`recall`	语义向量检索相关记忆
`consolidate`	手动触发记忆常规管道
`facts`	查询结构化事实
`goal`	创建/追踪目标
`failure`	记录失败事件（用于失败模式分析）
`hypothesis`	提出假设并自动验证
`namespace`	多 Agent 记忆隔离
`forget`	软删除记忆

接入方式极为简单：在 Cursor、Claude Desktop、Windsurf 等工具的 MCP 配置文件中添加一行 URL 即可，无需修改任何 Agent 代码。

技术栈：Go + PostgreSQL/pgvector 的精打经算

为何是 Go？

单二进制部署：CGO_ENABLED=0 静态编译，distroless/static 镜像仅 ~15MB，无运行时依赖
pgx 连接池：25 max conns / 5 min conns，远优于 Python ORM 的慷连接模式
goroutine 并发：Consolidation 多阶段管道可高效并行处理大批量 Episode

数据库层关键设计（internal/db/db.go）：

使用 pgvector-go 扩展存储向量嵌入，维度锁定机制防止 Embedding 模型切换导致维度不匹配
HNSW 索引（Hierarchical Navigable Small World）创建完全幂等，重复运行不报错
goose 嵌入式 SQL migration，支持自动版本升级
启动时检查 settings 表，防止配置错误导致向量存储失败

Embedder 接口设计（internal/embedder/）：

抽象 Embedder 接口，支持 OpenAI（text-embedding-3-small / 3-large）和 Ollama（nomic-embed-text）两种后端
向量缓存（internal/embedder/cache.go）避免重复 Embedding 计算
向量维度自适应：OpenAI 1536维 vs Ollama 768维，通过 STASH_VECTOR_DIM 环境变量统一控制

部署体验：3 分钟从零到记忆可用

一键启动（最推荐的本地方式）：

git clone https://github.com/alash3al/stash.git
cd stash
cp .env.example .env   # 填入你的 OpenAI API Key
docker compose up

纯本地模式（零 API Key）： 使用 Ollama 替代 OpenAI API，向量维数改为 768：

# host: 运行 Ollama
ollama pull nomic-embed-text
ollama pull qwen2.5:3b
# .env: 切换到 Ollama 配置块
STASH_OPENAI_BASE_URL=http://host.docker.internal:11434/v1
STASH_EMBEDDING_MODEL=nomic-embed-text
STASH_REASONER_MODEL=qwen2.5:3b
STASH_VECTOR_DIM=768
docker compose up

局限与争议

1. LLM 成本不可忽视

2. 向量维度锁定陷阱

3. Namespace 层级深度有限

Namespace slug 路径支持 / 分隔的层级，但代码中用正则 [a-z0-9][a-z0-9_-]{0,63} 限制单个层级段最大 64 字符，复杂多租户场景下可能遇到扩展瓶颈。

4. MCP Server 的 SSE 局限

当前 MCP 实现基于 SSE（Server-Sent Events），而非更现代的 WebSocket 双向通信。在高并发多 Agent 场景下，SSE 的单向拉模式可能造成工具调用排队延迟。

行业意义：从“上下文窗口竞赛”到“记忆基础设施”

Stash 的异化点在于：Go 单二进制 + MCP 协议 + 完整 Consolidation 管道，三者结合在开源社区中尚无直接对手。

快速上手路径

1. docker compose up（3分钟）
2. Cursor ~/.cursor/mcp.json 添加 {"url": "http://localhost:8080/sse"}
3. 对话中：call stash init → remember → recall → consolidate
4. 观察 facts 表中 LLM 合成的结构化知识

适用场景优先级：

⭐⭐⭐ 个人开发者/小团队：用 Cursor/Claude 写代码，需要 Agent 记住项目上下文
⭐⭐⭐ 多 Agent 协作：不同 Agent 通过 namespace 隔离记忆，避免互相干扰
⭐⭐ 客服/对话 Agent：需要跨会话记住用户偏好和历史互动
⭐ 研究原型：测试记忆增强对 Agent 任务完成率的影响