Session Forge

session-forge

不必再从零开始。 为 AI 编码助手提供持久的会话记忆。

Session-forge 为你的 AI 编码助手提供可跨会话保留的记忆。它会追踪决策、失败尝试、用户偏好和会话状态，让每次对话都能承接上一次，而不是从头开始。

适用于 Claude Code、Cursor、Windsurf 以及任何兼容 MCP 的客户端。

---

功能

• 会话崩溃恢复 — 保存工作检查点，从中断处继续
• 决策记录 — 记录选择 X 而非 Y 的原因，以便日后搜索
• 失败尝试追踪 — 避免重复犯同样的调试错误
• 用户档案 — AI 会记住你的姓名、偏好和项目
• 会话日志 — 记录整个过程，而不只是任务
• 完整上下文召回 — 通过一次调用，为新会话载入所有信息
• 数据管理 — 清理旧条目、导出所有数据、查看统计信息

快速开始

Claude Code

claude mcp add session-forge -- npx session-forge

Cursor / Windsurf

添加到 MCP 设置中：

{
  "mcpServers": {
    "session-forge": {
      "command": "npx",
      "args": ["-y", "session-forge"]
    }
  }
}

就这么简单。无需数据库、Docker 或配置文件。

---

15 个工具

会话

工具	描述	必填项
session_checkpoint	保存进行中工作的状态，以便崩溃后恢复	task, intent, next_steps
session_restore	检查上一个会话是否有中断的工作	—
session_complete	归档会话并标记为已完成	—

档案

工具	描述	必填项
profile_get	获取当前用户档案	—
profile_update	更新姓名、偏好、项目或备注	—

日志

工具	描述	必填项
journal_entry	记录会话摘要，包括突破和挫折	summary
journal_recall	检索近期会话日志	—

决策

工具	描述	必填项
decision_record	记录重要决策及其备选方案和理由	choice, reasoning
decision_search	按关键词搜索过往决策（支持 limit 参数）	query

失败尝试

工具	描述	必填项
dead_end_record	记录失败的方法以及从中吸取的教训	attempted, why_failed
dead_end_search	搜索过往失败尝试，避免重复犯错（支持 limit 参数）	query

上下文

工具	描述	必填项
full_context_recall	获取所有信息——档案、日志、决策和失败尝试。支持可选的 project 筛选条件。	—

数据管理

工具	描述	必填项
data_manage	清理旧条目、导出所有数据、清空存储区或查看统计信息	action
data_list	浏览已存储的条目及其编号摘要。支持搜索筛选。	store
data_delete	根据 data_list 输出中的索引删除指定条目	store, entry_index

data_manage 操作：

• stats — 查看所有存储区的条目数量和架构版本
• export — 将所有数据导出为 JSON
• prune — 删除超过 N 天的条目（默认：90）
• clear — 清空指定存储区（journal、decisions、dead_ends、profile 或 all）

data_list + data_delete 工作流：

1. 使用 store="decisions" 调用 data_list — 查看所有决策的编号列表
2. 使用 store="decisions", query="minecraft" 调用 data_list — 按关键词筛选
3. 使用 store="decisions", entry_index=3 调用 data_delete — 从列表中删除第 3 条

---

为什么选择 session-forge？

	session-forge	基础记忆 MCP	企业工具
设置	npx session-forge	各不相同	Docker + 数据库
死路追踪	是	否	否
决策记录	是	否	部分支持
会话崩溃恢复	是	部分支持	是
数据管理	是	否	部分支持
用户配置文件	是	部分支持	否
依赖项	2（SDK + zod）	各不相同	5-10+
基础设施	零（纯 JSON）	SQLite/ONNX/Vector DB	PostgreSQL + Redis
工具	15 个专用工具	4-9 个	37+ 个

---

配置

环境变量

变量	默认值	说明
SESSION_FORGE_DIR	~/.session-forge or %APPDATA%\session-forge	覆盖数据存储位置
SESSION_FORGE_STALE_HOURS	24	不活跃会话自动归档前的小时数

---

存储

所有数据均以纯 JSON 文件的形式存储在本地：

平台	位置
Linux / macOS	~/.session-forge/
Windows	%APPDATA%\session-forge\

使用环境变量 SESSION_FORGE_DIR 覆盖：

SESSION_FORGE_DIR=/custom/path npx session-forge

文件：

~/.session-forge/
  profile.json        # User preferences and projects
  journal.json        # Session summaries (last 100)
  decisions.json      # Decision log (last 200)
  dead-ends.json      # Failed approaches (last 100)
  sessions/
    active.json       # Current checkpoint
    history/          # Archived sessions

数据文件包含 schema_version 字段，以支持未来迁移。

---

CLAUDE.md 模板

将以下内容添加到项目的 CLAUDE.md，教 AI 何时调用各个工具：

## Session Flow

### Fresh session
1. Call `full_context_recall` — get profile, journals, decisions, dead ends
2. Call `session_restore` — check for interrupted work

### During work
- `decision_record` — when making a significant architectural choice
- `dead_end_record` — when something fails and we learn why
- `session_checkpoint` — every 10-15 tool calls during long sessions

### Session end
1. Call `journal_entry` — record what happened
2. Call `session_complete` — archive the checkpoint

---

更新日志

v2.0.1

• 添加免责声明：session-forge 与 SessionForge LLC（sessionforge.dev）无关联

v2.0.0

• 知识图谱 — 使用 related_dead_ends 和 led_to_decision 字段关联决策与死路
• 评分搜索 — 模糊匹配、标签筛选、AND/OR 搜索模式、相关性评分（取代基础字符串匹配）
• 使用统计 — 跟踪避免的死路、执行的搜索、恢复的会话
• MEMORY.md 同步 — full_context_recall 可以读取你的 MEMORY.md，并建议应保存到记忆中的决策和死路
• 增强检查点 — 现在会跟踪 errors_encountered、key_findings、decisions_made、dead_ends_hit
• 新增存储模块：links.js、search.js、stats.js、migrate.js
• 架构版本升级至 v2

v1.2.0

• 新增 data_list 工具 — 浏览存储条目并查看带编号的摘要，可选搜索筛选
• 新增 data_delete 工具 — 按索引精准删除单个条目
• 用户现在可以确切查看存储的内容，并删除任意条目

v1.1.0

• 新增 data_manage 工具（统计、导出、按时长清理、清空单个存储区）
• 为 full_context_recall 添加 project 筛选条件
• 为 decision_search 和 dead_end_search 添加 limit 参数
• 为 JSON 读取添加错误日志（之前会静默忽略解析失败）
• 通过 SESSION_FORGE_STALE_HOURS 添加可配置的过期会话超时
• 为数据文件添加 schema_version，以支持未来迁移
• 修复代码与 package.json 之间的版本不一致

v1.0.2

• 首次公开发布

---

许可证

MIT

---

重要声明

session-forge 与 SessionForge LLC（sessionforge.dev）无关联。

session-forge 于 2026 年 2 月 7 日 首次发布到 npm，早于 SessionForge LLC 的出现。我们与其产品或公司没有任何关联。

这很重要，原因如下：session-forge 将你的所有数据以纯 JSON 文件的形式存储在本地计算机上。没有任何数据会离开你的计算机。无需账户、服务器或第三方。

任何要求你将 AI 会话数据、编码习惯和终端访问权限交由其服务器处理的服务，都应让你思考：谁能访问这些数据，他们又会如何使用这些数据？

你的工作流、你的决策、你的代码——都属于你。它们应留在你的计算机上，由你掌控。session-forge 正是如此构建的，也将始终如此。

---

由 Jacob Terrell 构建