使用说明

内存脉冲MCP服务器

🧠 一个精确的、结构化的AI上下文记忆系统。为Claude Code设计的MCP服务器。

⭐ 如果你觉得这个项目有帮助，请给它一颗星 GitHub! 您的支持有助于我们改进！

❓ 为什么记忆脉冲？

现有AI内存解决方案的问题

问题	传统解决方案	内存脉冲
信息丢失	矢量压缩丢失细节	完全保留上下文
检索不准确	仅语义搜索缺少精确匹配	多级：精确→ 全文→ 语义
决策差距	存储结论，而不是推理	结构化：问题→ 分析→ 选项→ 决定
上下文碎片化	零散、无关的记忆	关系链和时间线跟踪

与其他存储系统的比较

功能	内存脉冲	mem0	Zep	LangChain内存
存储	全上下文（无压缩）	矢量嵌入	矢量+图形	矢量嵌入
检索策略	L1精确→ L2全文→ L3语义	仅语义	语义+时间	仅语义
决策跟踪	✅ 强制结构化字段	❌	❌	❌
关系图	✅ 内置	❌	✅	❌
时间线视图	✅ 内置	❌	✅	❌
MCP本地	✅	❌	❌	❌
本地优先	✅ SQLite	云依赖	云依赖
零配置	✅	❌	❌	❌

🚀 特性

🧠 完整的上下文保存 -无压缩，无信息丢失
🔍 多级检索 -L1完全匹配→ L2全文搜索→ L3语义搜索
📋 结构化内存类型 -决策/解决方案/会话/代码/错误/配置
🔗 关系链 -追踪记忆是如何联系和演变的
📅 时间线视图 -观察记忆随时间的演变
🎯 强制结构 -AI必须提供完整的上下文（没有懒惰的摘要）
💾 本地优先 -SQLite存储，您的数据与您同在
⚡ 零配置 -开箱即用

📦 快速开始

选项1：使用npx运行（推荐）

npx memory-pulse-mcp-server

选项2：全局安装

npm install -g memory-pulse-mcp-server
memory-pulse-mcp

选项3：从源代码构建

git clone https://github.com/jiahuidegit/memory-mcp-server.git
cd memory-mcp-server
pnpm install
pnpm build

🔄 更新到最新版本

如果使用npx（推荐）

npx会自动使用最新版本，只需重新启动MCP客户端即可。

如果全局安装

npm update -g memory-pulse-mcp-server
# Or reinstall
npm install -g memory-pulse-mcp-server@latest

检查当前版本

npm list -g memory-pulse-mcp-server

🎮 MCP客户端配置

克劳德代码

创建 .mcp.json 在您的项目目录中：

{
  "mcpServers": {
    "memory-pulse": {
      "command": "npx",
      "args": ["-y", "memory-pulse-mcp-server"]
    }
  }
}

或全局配置 ~/.claude/mcp.json:

{
  "mcpServers": {
    "memory-pulse": {
      "command": "npx",
      "args": ["-y", "memory-pulse-mcp-server"]
    }
  }
}

克劳德桌面版

编辑配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memory-pulse": {
      "command": "npx",
      "args": ["-y", "memory-pulse-mcp-server"]
    }
  }
}

配置后重新启动客户端。

⚙️ 环境变量

变量	描述	默认值
`MEMORY_STORAGE`	存储类型： `sqlite` 或 `postgresql`	`sqlite`
`MEMORY_DB_PATH`	SQLite数据库文件路径	`~/.emp/memory.db`
`DATABASE_URL`	PostgreSQL连接字符串（PostgreSQL需要）	-

SQLite存储（默认）

零配置，开箱即用。数据存储在 ~/.emp/memory.db:

{
  "mcpServers": {
    "memory-pulse": {
      "command": "npx",
      "args": ["-y", "memory-pulse-mcp-server"]
    }
  }
}

自定义SQLite路径

{
  "mcpServers": {
    "memory-pulse": {
      "command": "npx",
      "args": ["-y", "memory-pulse-mcp-server"],
      "env": {
        "MEMORY_DB_PATH": "/path/to/your/memory.db"
      }
    }
  }
}

PostgreSQL存储

对于生产部署或团队使用：

{
  "mcpServers": {
    "memory-pulse": {
      "command": "npx",
      "args": ["-y", "memory-pulse-mcp-server"],
      "env": {
        "MEMORY_STORAGE": "postgresql",
        "DATABASE_URL": "postgresql://user:password@localhost:5432/memory_pulse"
      }
    }
  }
}

备注：使用PostgreSQL时，MCP服务器将在第一次运行时自动创建所需的表。

🛠️ MCP工具

记忆存储

工具	说明
`mpulse_store`	具有自动分类功能的智能内存存储
`mpulse_store_decision`	存储架构决策（强制填写字段）
`mpulse_store_solution`	存储问题解决方案（问题→ 根本原因→ 解决方案）
`mpulse_store_session`	存储会话摘要（会话结束时调用）

记忆检索

工具	说明
`mpulse_recall`	多策略记忆检索
`mpulse_timeline`	查看项目时间线
`mpulse_relations`	查询内存关系链

💡 使用示例

存储决策

当你做出架构决策时，AI会调用 mpulse_store_decision:

User: Let's use Zustand for state management instead of Redux

AI: [calls mpulse_store_decision]
{
  "question": "Which state management solution to use?",
  "options": [
    { "name": "Redux", "pros": ["Mature ecosystem", "DevTools"], "cons": ["Boilerplate heavy"] },
    { "name": "Zustand", "pros": ["Lightweight", "TypeScript friendly"], "cons": ["Smaller ecosystem"] }
  ],
  "chosen": "Zustand",
  "reason": "Project is medium-sized, prioritizing development efficiency. Zustand has lower learning curve.",
  "projectId": "my-app"
}

✅ Decision stored with ID: mem_xxx

存储解决方案

当你解决一个问题时，AI会呼叫 mpulse_store_solution:

User: Fixed the memory leak in useEffect

AI: [calls mpulse_store_solution]
{
  "problem": "Memory leak warning in React component",
  "rootCause": "Async operation continues after component unmount",
  "solution": "Added cleanup function in useEffect to cancel pending requests",
  "projectId": "my-app"
}

✅ Solution stored with ID: mem_xxx

回忆往事

当您需要以前会话的上下文时：

User: What did we decide about state management?

AI: [calls mpulse_recall]
{
  "query": "state management",
  "projectId": "my-app",
  "strategy": "fulltext"
}

Found: Decision from 2 days ago - Chose Zustand because...

查看时间线

User: Show me what we worked on this week

AI: [calls mpulse_timeline]
{
  "projectId": "my-app",
  "limit": 20
}

Timeline:
- Jan 15: Decision - State management (Zustand)
- Jan 15: Solution - Memory leak fix
- Jan 14: Decision - API architecture (REST vs GraphQL)
...

查询关系

User: What decisions are related to our API design?

AI: [calls mpulse_relations]
{
  "memoryId": "mem_api_decision",
  "depth": 2
}

Relationships:
- mem_api_decision (Decision: REST API)
  ├── mem_auth_solution (Solution: JWT implementation)
  └── mem_error_handling (Decision: Error response format)

📝 AI提示配置（CLAUDE.md）

要使AI自动存储和检索记忆，请将以下提示规则添加到项目的 CLAUDE.md 或全球 ~/.claude/CLAUDE.md:

会话启动协议（推荐）

在CLAUDE.md的开头添加，以确保AI在会话开始时检索历史记录：

# ⚠️ Session Startup Protocol (Highest Priority)

**Before processing any user request, execute the following steps:**

## Step 1: Extract Project Name
Extract project name from current working directory (last folder name)
Example: `/Users/xxx/work/my-app` → projectId = `my-app`

## Step 2: Retrieve History (Mandatory)
Call mpulse_recall to retrieve project history:
- query: "project context architecture decisions unfinished tasks config"
- projectId: extracted project name

## Step 3: Report Memory Results
- Has memories → Brief summary before processing user request
- No memories → State "No history found" then process user request

**⛔ Processing request without memory retrieval = Violation**

汽车商店规则

添加以下规则，使AI在关键点自动存储记忆：

# Memory Pulse Rules

## Mandatory Storage Triggers

| Trigger | Tool | Required Fields |
|---------|------|-----------------|
| After architecture/tech decisions | `mpulse_store_decision` | question, options, chosen, reason |
| After solving complex problems | `mpulse_store_solution` | problem, rootCause, solution |
| Before session ends | `mpulse_store_session` | summary, unfinished tasks |
| Important config info | `mpulse_store` | content, rawContext |

## Storage Quality Requirements

### content vs rawContext (Important!)
- **content**: Brief summary (1-2 sentences), for list display
- **rawContext**: Complete original data, including all details

### Example
```json
{
  "content": "Configured PostgreSQL database connection",
  "rawContext": {
    "host": "10.10.1.12",
    "port": 5432,
    "database": "my_app",
    "user": "postgres",
    "connectionString": "postgresql://postgres:xxx@10.10.1.12:5432/my_app",
    "configFile": "/opt/app/.env"
  }
}

检索触发器

遇到类似问题→ 先搜索现有解决方案
在技术决策之前→ 检查以前的决策记录
继续以前的工作→ 检索上次会话摘要


### Complete Configuration Example

```markdown
# CLAUDE.md

## Session Startup Protocol
[Session startup protocol content above]

## Memory Pulse Usage Rules

### Storage Rules
- After tech decisions → Must call mpulse_store_decision
- After solving problems → Must call mpulse_store_solution
- Before session ends → Must call mpulse_store_session
- User says "remember this" → Immediately call mpulse_store

### Retrieval Rules
- Session start → Auto-retrieve project history
- Facing issues → Search for related solutions first
- Tech decisions → Check previous decision records

### projectId Naming Convention
- Use current project folder name as projectId
- Cross-project knowledge uses projectId = "global"

🔍 检索算法

记忆脉冲使用 三级级联检索策略:

┌─────────────────────────────────────────────────────┐
│                    User Query                        │
└─────────────────────┬───────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────┐
│  L1: Exact Match (< 10ms)                           │
│  - projectId + type + keywords index                │
│  - Returns if matches ≥ 5                           │
└─────────────────────┬───────────────────────────────┘
                      ▼ (if insufficient)
┌─────────────────────────────────────────────────────┐
│  L2: Full-text Search (< 100ms)                     │
│  - SQLite FTS5 / PostgreSQL full-text               │
│  - Chinese + English tokenization                   │
│  - Returns if matches ≥ 3                           │
└─────────────────────┬───────────────────────────────┘
                      ▼ (if insufficient)
┌─────────────────────────────────────────────────────┐
│  L3: Semantic Search (< 500ms)                      │
│  - Embedding similarity (optional)                  │
│  - Fallback for fuzzy queries                       │
└─────────────────────────────────────────────────────┘

为什么采用这种方法？

精度第一：精确匹配更快、更准确
优雅降级：在需要时回到更广泛的搜索
无误报：语义搜索是最后的手段，不是默认的

📊 内存类型

类型	用例	必填字段
`decision`	架构选择	问题、选项、选择、原因
`solution`	问题修复	问题、根本原因、解决方案
`session`	会议总结	总结、决定、下一步
`code`	代码实现	内容、工件
`error`	错误记录	内容，stackTrace
`config`	配置信息	内容、设置

🖥️ Web仪表板

Memory Pulse包括一个漂亮的Web仪表板，用于可视化和管理您的记忆。

特性

特性	描述
内存管理	使用现代UI浏览、搜索和创建回忆
时间线视图	观察你的记忆力随时间的演变
关系图	内存连接的交互式可视化
项目筛选	一键切换项目
全文搜索	快速找到任何内存

📖 部署指导

选择适合您需求的部署方案：

场景1:SQLite（本地个人使用）

最适合：个人开发人员，轻量级使用，快速入门。

┌─────────────────────────────────────────┐
│  Your Local Machine                      │
│                                         │
│  Claude Code → MCP Server               │
│                    ↓                    │
│           ~/.emp/memory.db              │
│                    ↑                    │
│              Web Dashboard              │
│                    ↓                    │
│           http://localhost:3001         │
└─────────────────────────────────────────┘

步骤1：配置MCP服务器

添加到您的Claude MCP配置中(~/.claude.json 或 .mcp.json):

{
  "mcpServers": {
    "memory-pulse": {
      "command": "npx",
      "args": ["-y", "memory-pulse-mcp-server"]
    }
  }
}

第二步：重启克劳德 以激活MCP服务器。

步骤3：在本地启动Web仪表板

# Clone the repository
git clone https://github.com/jiahuidegit/memory-mcp-server.git
cd memory-mcp-server

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start API server (reads config from ~/.emp/runtime-config.json)
pnpm --filter @emp/api dev &

# Start Web Dashboard
pnpm --filter @emp/web dev

第四步：打开http://localhost:3001 在您的浏览器中。

运作原理：当MCP服务器启动时，它会将其配置写入 ~/.emp/runtime-config.json.API服务器读取此文件并自动连接到同一SQLite数据库。

场景2:PostgreSQL（团队/生产使用）

最适合：团队协作、多设备访问、生产部署。

┌──────────────────┐     ┌──────────────────┐
│  User A (Local)  │     │  User B (Local)  │
│  MCP Server      │     │  MCP Server      │
└────────┬─────────┘     └────────┬─────────┘
         │                        │
         ↓                        ↓
      ┌─────────────────────────────┐
      │      PostgreSQL Database    │
      │   (Shared data storage)     │
      └──────────────┬──────────────┘
                     ↑
      ┌──────────────┴──────────────┐
      │      Web Dashboard          │
      │   (Deployed on server)      │
      │   http://your-server:3001   │
      └─────────────────────────────┘

步骤1：设置PostgreSQL数据库

# Create database
createdb memory_pulse

# Or use Docker
docker run -d --name memory-pulse-db \
  -e POSTGRES_DB=memory_pulse \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=your_password \
  -p 5432:5432 \
  postgres:15

步骤2：为每个用户配置MCP服务器

添加到Claude MCP配置(~/.claude.json 或 .mcp.json):

{
  "mcpServers": {
    "memory-pulse": {
      "command": "npx",
      "args": ["-y", "memory-pulse-mcp-server"],
      "env": {
        "MEMORY_STORAGE": "postgresql",
        "DATABASE_URL": "postgresql://postgres:your_password@your-db-server:5432/memory_pulse"
      }
    }
  }
}

步骤3：在服务器上部署Web仪表板

# On your web server
git clone https://github.com/jiahuidegit/memory-mcp-server.git
cd memory-mcp-server

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Set environment variables
export MEMORY_STORAGE=postgresql
export DATABASE_URL="postgresql://postgres:your_password@your-db-server:5432/memory_pulse"

# Start API server
pnpm --filter @emp/api start &

# Start Web Dashboard
pnpm --filter @emp/web start

步骤4：访问Web仪表板 在 http://your-server:3001

关键点：MCP服务器和Web仪表板都必须使用 相同的DATABASE_URL 查看相同的数据。

配置优先

系统按以下顺序读取配置（首先找到获胜）：

环境变量 - MEMORY_STORAGE, DATABASE_URL, MEMORY_DB_PATH
运行时配置文件 - ~/.emp/runtime-config.json （MCP服务器编写）
默认值 -SQLite位于 ~/.emp/memory.db

Docker部署（生产）

对于生产环境，您可以使用Docker：

# Dockerfile
FROM node:18-alpine
WORKDIR /app
RUN npm install -g pnpm
COPY . .
RUN pnpm install && pnpm build
EXPOSE 3000 3001
CMD ["sh", "-c", "pnpm --filter @emp/api start & pnpm --filter @emp/web start"]

# docker-compose.yml
version: '3.8'
services:
  memory-pulse:
    build: .
    ports:
      - "3000:3000"
      - "3001:3001"
    environment:
      - MEMORY_STORAGE=postgresql
      - DATABASE_URL=postgresql://postgres:password@db:5432/memory_pulse
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=memory_pulse
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

docker-compose up -d

截图

仪表板主页

关系图

🏗️ 建筑

┌─────────────────────────────────────────────────────────────────┐
│                        Memory Pulse System                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐       │
│  │ Claude Code  │    │Claude Desktop│    │  Other MCP   │       │
│  │              │    │              │    │   Clients    │       │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘       │
│         │                   │                   │                │
│         └───────────────────┼───────────────────┘                │
│                             │                                    │
│                             ▼                                    │
│              ┌─────────────────────────────┐                     │
│              │     MCP Server (stdio)      │                     │
│              │   memory-pulse-mcp-server   │                     │
│              └─────────────┬───────────────┘                     │
│                            │                                     │
│         ┌──────────────────┼──────────────────┐                  │
│         ▼                  ▼                  ▼                  │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐            │
│  │   SQLite    │   │ PostgreSQL  │   │   API       │            │
│  │  (Local)    │   │  (Remote)   │   │  Server     │            │
│  └─────────────┘   └──────┬──────┘   └──────┬──────┘            │
│                           │                 │                    │
│                           └────────┬────────┘                    │
│                                    ▼                             │
│                          ┌─────────────────┐                     │
│                          │  Web Dashboard  │                     │
│                          │  (Next.js App)  │                     │
│                          └─────────────────┘                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

组件

组件	描述	技术
MCP 服务器	通过MCP协议进行核心内存操作	Node.js、TypeScript
存储层	灵活的存储后端	SQLite/PPostgreSQL
API服务器	用于web访问的RESTful API	Express.js
Web仪表板	可视化管理界面	Next.js 15，React 19

🔒 安全与隐私

本地优先 -所有数据都存储在SQLite本地，不依赖于云
您的数据 -数据库文件归您所有，随时备份/迁移
无遥测 -零数据收集或打电话回家
项目隔离 -由projectId隔离的记忆

🗺️ 路线图

[x] MCP服务器核心功能
[x] SQLite本地存储
[x] PostgreSQL云支持
[x] 多级检索（精确+全文）
[x] 决策/解决方案/会话结构化存储
[x] 可视化Web仪表板
[]用于手动操作的CLI工具
[]语义搜索（嵌入）
[]团队协作功能

📊 明星历史

🤝 贡献

欢迎问题和拉取请求！

# Development
git clone https://github.com/jiahuidegit/memory-mcp-server.git
cd memory-mcp-server
pnpm install
pnpm build
pnpm test

📄 许可证

该项目根据 MIT许可证.

⭐ 如果你觉得这个项目有帮助，请给它一颗星！

🤝 欢迎随时提出问题或提交PR以进行改进！