使用说明

synapse-memory

Persistent session memory for AI coding assistants

An MCP server that gives your AI assistant a memory that lasts.
Every session — files touched, decisions made, patterns discovered — recorded locally in SQLite.
Works with Claude Code, Cursor, Aider, and any MCP-compatible tool.

Quick Start • Features • Tool Reference • Roadmap

问题

人工智能编码助理在每次会话开始时都会失忆。他们不知道你昨天决定了什么，上周重构了哪些文件，或者你的代码库遵循了什么模式。你重新解释上下文。他们重新发现了模式。每个人都在浪费时间。

解决方案

突触记忆记录每个编码会话中发生的事情，并在下一个编码会话开始时提供。决策依然存在。模式被记住。已解决的错误将保持解决状态。

所有数据在会话之间、重启之间永远保存在本地SQLite文件中。 没有云。没有账户。没有基础设施。

快速开始

一个命令（克劳德代码）

claude mcp add synapse-memory -- npx -y synapse-memory

或者添加到您的MCP配置中

克劳德代码 (~/.claude/mcp.json 或项目 .mcp.json):

{
  "mcpServers": {
    "synapse-memory": {
      "command": "npx",
      "args": ["-y", "synapse-memory"]
    }
  }
}

光标（设置→ MCP服务器）：

{
  "synapse-memory": {
    "command": "npx",
    "args": ["-y", "synapse-memory"]
  }
}

就是这样。没有数据库可以运行。没有API密钥。没有配置。数据存在于 ~/.synapse-memory/memory.db.

特性

v0.2亮点

特性	描述
多代理支持	适用于Claude Code、Cursor、Aider、OpenClaw——任何MCP客户端
价值分析	追踪突触记忆为您节省了多少时间
智能上下文排名	分支机构意识得分排名最近，相关会议更高
重复检测	防止推广相同或近乎重复的知识
文件重要性	根据访问模式跟踪哪些文件最重要
代理使用统计信息	查看您使用哪些AI工具以及使用频率

跨会话记忆在行动

┌─────────────────────── SESSION 1 ───────────────────────┐
│                                                         │
│  > session_start({projectPath: "/myapp"})               │
│  Session started: a1b2c3d4                              │
│  Agent: Claude Code                                     │
│                                                         │
│  > record_event({                                       │
│      detail: { type: "decision",                        │
│        title: "Use repository pattern",                 │
│        rationale: "Clean data access separation" }      │
│    })                                                   │
│  Event recorded: decision                               │
│                                                         │
│  > promote_knowledge({                                  │
│      title: "Use repository pattern",                   │
│      content: "All data access through repository       │
│               functions. Never access db directly.",    │
│      knowledgeType: "decision"                          │
│    })                                                   │
│  Knowledge promoted.                                    │
│                                                         │
│  > session_end({                                        │
│      summary: "Built storage layer with repo pattern"   │
│    })                                                   │
│  Session completed. Duration: 45 min. Events: 12.       │
│                                                         │
└─────────────────────────────────────────────────────────┘

  ════════════════ Time passes. New day. ════════════════

┌─────────────────────── SESSION 2 ───────────────────────┐
│                                                         │
│  > session_start({projectPath: "/myapp"})               │
│                                                         │
│  Session started: e5f6g7h8                              │
│  Project: /myapp                                        │
│  Branch: main                                           │
│  Agent: Cursor                                          │
│                                                         │
│  --- Recent Sessions (ranked by relevance) ---          │
│  [2026-02-16] Built storage layer (score: 0.95)         │
│    Decision: Use repository pattern                     │
│    Pattern: Immutable return types with readonly        │
│                                                         │
│  --- Project Knowledge ---                              │
│  [decision] Use repository pattern: All data access     │
│    through repository functions.                        │
│                                                         │
│  --- Important Files ---                                │
│  src/storage/sessions.ts (score: 2.4 | 15 reads)        │
│  src/utils.ts (score: 1.8 | 10 reads, 5 edits)          │
│                                                         │
│  --- Value Summary ---                                  │
│  Sessions: tracked | Knowledge surfaced: 5 | ~15m saved │
│                                                         │
└─────────────────────────────────────────────────────────┘

无论您使用哪种AI工具，会话2都会自动显示会话1中的决策、模式、重要文件和推广知识。

建筑

  session_start ──> record_event (repeat) ──> session_end
       │                                           │
       │  Returns ranked context from              │  Computes metrics,
       │  past sessions + knowledge                │  stores summary
       │                                           │
       ▼                                           ▼
  ┌─────────────────────────────────────────────────────┐
  │                  SQLite (persisted)                 │
  │                ~/.synapse-memory/memory.db          │
  │                                                     │
  │  sessions ─── events ─── knowledge ─── value_metrics│
  │      │                       │                      │
  │  agents ─── file_importance ─── knowledge_usage     │
  └─────────────────────────────────────────────────────┘
       ▲                                           ▲
       │                                           │
    recall / stats                        promote_knowledge
    get_knowledge                         get_value_metrics

工具参考

突触记忆提供 8个MCP工具:

会话生命周期

`session_start`

开始新的编码会话。自动检测git分支、代理类型，并返回过去会话的上下文。

参数	类型	必填	说明
`projectPath`	string	✓	工作目录/项目根目录
`branch`	string		Git分支（自动检测）
`gitCommit`	string		当前HEAD SHA（自动检测）
`agentType`	string		`claude-code`
`agentVersion`	string		AI代理的版本

退货： 会话ID、最近会话排名、推广知识、重要文件、价值摘要。

`session_end`

使用计算出的指标结束当前会话。

参数	类型	必填	说明
`sessionId`	string	✓	会话开始时的会话ID
`summary`	string		完成了什么
`gitCommit`	string		会话结束时的头部SHA

退货： 会话指标（持续时间、事件、接触的文件）。

事件记录

`record_event`

在会议期间记录一个重要事件。自动跟踪文件重要性。

参数	类型	必填	说明
`sessionId`	string	✓	活动会话ID
`eventType`	string	✓	事件类型（见下文）
`detail`	对象	✓	事件特定细节

事件类型和细节形状：

// File operation
{ type: "file_op", path: "/src/index.ts", operation: "read" | "write" | "edit" }

// Tool call
{ type: "tool_call", toolName: "Bash", params?: "npm test" }

// Decision
{ type: "decision", title: "Use SQLite", rationale: "Zero infrastructure" }

// Pattern
{ type: "pattern", description: "Repository pattern", files: ["/src/storage/"] }

// Error resolved
{ type: "error_resolved", error: "TypeError...", resolution: "Added null check", files: [...] }

// Milestone
{ type: "milestone", summary: "Storage layer complete" }

知识管理

`promote_knowledge`

将会议发现提升到项目层面的知识。包括重复检测。

参数	类型	必填	说明
`projectPath`	string	✓	项目根路径
`title`	string	✓	简短标题
`content`	string	✓	详细内容
`knowledgeType`	string	✓	`decision`
`tags`	string[]		分类标签
`sessionId`	string		源会话ID
`allowDuplicate`	boolean		即使检测到重复，也强制升级
`supersedes`	string		这将取代知识ID

退货： 使用知识ID进行确认，如果存在类似的知识，则发出重复警告。

`get_knowledge`

检索提升的项目级知识。

参数	类型	必填	说明
`projectPath`	string	✓	项目根路径
`knowledgeType`	string		按类型筛选
`limit`	number		最大结果数（默认20，最大100）

查询和分析

`recall`

使用分支感知评分查询过去的会话以获取相关知识。

参数	类型	必填	说明
`projectPath`	string	✓	项目根路径
`query`	string		全文搜索词
`branch`	string		按git分支筛选
`eventType`	string		按事件类型筛选
`limit`	number		最大结果数（默认10，最大50）

退货： 对会话进行排序，包括摘要、决定和模式。

`stats`

会话分析，包括代理使用细分。

参数	类型	必填	说明
`projectPath`	string	✓	项目根路径
`period`	string		`day`

退货： 会话计数、花费的时间、顶级文件、代理使用情况、价值指标。

`get_value_metrics`

综合价值报告，显示突触记忆为您节省了多少时间。

参数	类型	必填	说明
`projectPath`	string	✓	项目根路径
`hourlyRate`	number		$计算的小时费率（默认值：50）

退货： 会话跟踪，知识浮出水面，节省时间估算和细分。

数据存储

所有数据都保留在您的机器上。没有任何东西被发送到任何地方。

~/.synapse-memory/
  memory.db          # SQLite database (WAL mode)

覆盖位置：

SYNAPSE_MEMORY_DIR=/custom/path synapse-memory

架构（v3）

表	目的
`sessions`	会话生命周期+代理跟踪
`session_events`	会议期间记录的事件
`promoted_knowledge`	具有重复数据消除的项目级知识
`agents`	代理注册表（克劳德代码、游标等）
`file_importance`	文件访问跟踪和评分
`knowledge_usage`	当知识浮出水面/被唤起时
`value_metrics`	每个项目的总价值跟踪
`synapse_sync_config`	未来Synapse同步配置

路线图

v0.1——本地会话内存✅

[x] 会话生命周期(session_start, session_end)
[x] 6种事件类型的事件记录
[x] 跨会话上下文注入
[x] 全文搜索(recall)
[x] 会话分析(stats)
[x] 知识推广体系
[x] 通过迁移进行架构版本控制

v0.2——多代理和价值跟踪✅ （当前）

[x] 多代理支持 --适用于Claude Code、Cursor、Aider、OpenClaw
[x] Agent检测 --从环境变量中自动检测代理
[x] 价值分析 --跟踪知识浮出水面，节省时间，$价值
[x] 分行感知评分 --按分支相关性对上下文进行排名
[x] 文件重要性 --跟踪访问最多的文件
[x] 重复检测 --防止冗余的知识推广
[x] 知识替代 --将旧知识标记为已被取代

v0.3——语义搜索和嵌入

[ ] 局部矢量搜索 --嵌入会话摘要以进行语义回忆
[ ] 基于相似性的回忆 --“查找与我现在所做的类似的会话”
[ ] 智能上下文注入 --读取新文件时自动建议过去的决定
[ ] 跨项目知识 --跨相关项目共享模式

v0.4--团队智能（Synapse同步）

[ ] Synapse同步 --选择推送到托管的Synapse实例
[ ] 团队知识库 --查询共享团队知识
[ ] 冲突解决 --处理相互矛盾的决定
[ ] 知识生命周期 --弃用和版本知识

v0.5——主动智能

[ ] 上下文预测 --预测克劳德需要什么样的背景
[ ] Auto CLAUDE.md --从推广的知识生成CLAUDE.md
[ ] 会话模板 --任务类型的预加载上下文
[ ] 回归检测 --对重新引入的错误发出警报

未来

[ ] IDE集成 --VS代码/光标扩展名
[ ] 分析仪表板 --会话历史记录的Web UI
[ ] 插件系统 --自定义事件类型和提取器

发展

git clone https://github.com/WorldFlowAI/synapse-memory
cd synapse-memory
npm install
npm test              # 151 tests, 84%+ coverage
npm run build         # Compile to dist/

项目结构

src/
  index.ts              # Entry point (stdio transport)
  server.ts             # MCP server + tool registration
  types.ts              # Core types (Synapse-aligned)
  utils.ts              # Git helpers, agent detection
  storage/
    database.ts         # SQLite + migrations (v3)
    sessions.ts         # Session CRUD + metrics
    events.ts           # Event CRUD
    knowledge.ts        # Knowledge CRUD + dedup
    agents.ts           # Agent registry
    file-importance.ts  # File access tracking
    knowledge-usage.ts  # Usage tracking
    value-metrics.ts    # Value aggregation
  context/
    scoring.ts          # Branch-aware relevance scoring
    deduplication.ts    # Content hashing + duplicate detection
  tools/
    session-start.ts    # session_start
    session-end.ts      # session_end
    record-event.ts     # record_event
    recall.ts           # recall
    stats.ts            # stats
    knowledge.ts        # promote_knowledge + get_knowledge
    value-metrics.ts    # get_value_metrics
tests/
  storage/              # Storage layer tests
  context/              # Scoring + dedup tests
  tools/                # Tool handler tests
  utils/                # Utility tests

手动MCP测试

npm run build

# Test session start with agent type
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"session_start","arguments":{"projectPath":"/tmp/test","agentType":"cursor"}}}' | node dist/index.js

# Test value metrics
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_value_metrics","arguments":{"projectPath":"/tmp/test"}}}' | node dist/index.js

Synapse集成

突触记忆是突触，LLM应用程序的语义缓存层。当团队同步功能在v0.4中发布时，类型和模式的设计是为了实现平稳的升级路径。

许可证

MIT与Commons条款

您可以出于任何目的自由使用、修改和分发突触记忆，包括在组织内的商业用途。Commons条款限制将突触存储器作为与WorldFlow AI产品竞争的托管服务出售。

使用说明

synapse-memory

问题

解决方案

快速开始

一个命令（克劳德代码）

或者添加到您的MCP配置中

特性

v0.2亮点

跨会话记忆在行动

建筑

工具参考

会话生命周期

session_start

session_end

事件记录

record_event

知识管理

promote_knowledge

get_knowledge

查询和分析

recall

stats

get_value_metrics