memory-pulse-server
Memory Pulse - ็ฒพๅใ็ปๆๅ็ AI ไธไธๆ่ฎฐๅฟ็ณป็ป MCP Server
Installation
npx memory-pulse-mcp-serverAsk AI about memory-pulse-server
Powered by Claude ยท Grounded in docs
I know everything about memory-pulse-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Memory Pulse MCP Server
๐ง A precise, structured AI context memory system. MCP Server designed for Claude Code.
โญ If you find this project helpful, please give it a star on GitHub! Your support helps us improve!
โ Why Memory Pulse?
The Problem with Existing AI Memory Solutions
| Problem | Traditional Solutions | Memory Pulse |
|---|---|---|
| Information Loss | Vector compression loses details | Complete context preservation |
| Imprecise Retrieval | Semantic-only search misses exact matches | Multi-level: Exact โ Full-text โ Semantic |
| Decision Gap | Stores conclusions, not reasoning | Structured: Problem โ Analysis โ Options โ Decision |
| Context Fragmentation | Scattered, unrelated memories | Relationship chains & timeline tracking |
Comparison with Other Memory Systems
| Feature | Memory Pulse | mem0 | Zep | LangChain Memory |
|---|---|---|---|---|
| Storage | Full context (no compression) | Vector embeddings | Vector + Graph | Vector embeddings |
| Retrieval Strategy | L1 Exact โ L2 Full-text โ L3 Semantic | Semantic only | Semantic + Temporal | Semantic only |
| Decision Tracking | โ Forced structured fields | โ | โ | โ |
| Relationship Graph | โ Built-in | โ | โ | โ |
| Timeline View | โ Built-in | โ | โ | โ |
| MCP Native | โ | โ | โ | โ |
| Local-first | โ SQLite | Cloud-dependent | Cloud-dependent | Varies |
| Zero Config | โ | โ | โ | โ |
๐ Features
- ๐ง Complete Context Preservation - No compression, no information loss
- ๐ Multi-level Retrieval - L1 Exact match โ L2 Full-text search โ L3 Semantic search
- ๐ Structured Memory Types - Decision / Solution / Session / Code / Error / Config
- ๐ Relationship Chains - Track how memories relate and evolve
- ๐ Timeline View - See memory evolution over time
- ๐ฏ Forced Structure - AI must provide complete context (no lazy summaries)
- ๐พ Local-first - SQLite storage, your data stays with you
- โก Zero Config - Works out of the box
๐ฆ Quick Start
Option 1: Run with npx (Recommended)
npx memory-pulse-mcp-server
Option 2: Global Installation
npm install -g memory-pulse-mcp-server
memory-pulse-mcp
Option 3: Build from Source
git clone https://github.com/jiahuidegit/memory-mcp-server.git
cd memory-mcp-server
pnpm install
pnpm build
๐ Update to Latest Version
If using npx (Recommended)
npx automatically uses the latest version, just restart your MCP client.
If globally installed
npm update -g memory-pulse-mcp-server
# Or reinstall
npm install -g memory-pulse-mcp-server@latest
Check current version
npm list -g memory-pulse-mcp-server
๐ฎ MCP Client Configuration
Claude Code
Create .mcp.json in your project directory:
{
"mcpServers": {
"memory-pulse": {
"command": "npx",
"args": ["-y", "memory-pulse-mcp-server"]
}
}
}
Or global configuration at ~/.claude/mcp.json:
{
"mcpServers": {
"memory-pulse": {
"command": "npx",
"args": ["-y", "memory-pulse-mcp-server"]
}
}
}
Claude Desktop
Edit the configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"memory-pulse": {
"command": "npx",
"args": ["-y", "memory-pulse-mcp-server"]
}
}
}
Restart the client after configuration.
โ๏ธ Environment Variables
| Variable | Description | Default |
|---|---|---|
MEMORY_STORAGE | Storage type: sqlite or postgresql | sqlite |
MEMORY_DB_PATH | SQLite database file path | ~/.emp/memory.db |
DATABASE_URL | PostgreSQL connection string (required for postgresql) | - |
SQLite Storage (Default)
Zero configuration, works out of the box. Data is stored in ~/.emp/memory.db:
{
"mcpServers": {
"memory-pulse": {
"command": "npx",
"args": ["-y", "memory-pulse-mcp-server"]
}
}
}
Custom SQLite Path
{
"mcpServers": {
"memory-pulse": {
"command": "npx",
"args": ["-y", "memory-pulse-mcp-server"],
"env": {
"MEMORY_DB_PATH": "/path/to/your/memory.db"
}
}
}
}
PostgreSQL Storage
For production deployments or team usage:
{
"mcpServers": {
"memory-pulse": {
"command": "npx",
"args": ["-y", "memory-pulse-mcp-server"],
"env": {
"MEMORY_STORAGE": "postgresql",
"DATABASE_URL": "postgresql://user:password@localhost:5432/memory_pulse"
}
}
}
}
Note: When using PostgreSQL, the MCP Server will automatically create the required tables on first run.
๐ ๏ธ MCP Tools
Memory Storage
| Tool | Description |
|---|---|
mpulse_store | Smart memory storage with auto-classification |
mpulse_store_decision | Store architectural decisions (forced complete fields) |
mpulse_store_solution | Store problem solutions (problem โ root cause โ solution) |
mpulse_store_session | Store session summaries (call at session end) |
Memory Retrieval
| Tool | Description |
|---|---|
mpulse_recall | Multi-strategy memory retrieval |
mpulse_timeline | View project timeline |
mpulse_relations | Query memory relationship chains |
๐ก Usage Examples
Store a Decision
When you make an architectural decision, AI calls 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
Store a Solution
When you solve a problem, AI calls 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
Recall Memories
When you need context from previous sessions:
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...
View Timeline
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)
...
Query Relationships
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 Prompt Configuration (CLAUDE.md)
To make AI automatically store and retrieve memories, add the following prompt rules to your project's CLAUDE.md or global ~/.claude/CLAUDE.md:
Session Startup Protocol (Recommended)
Add at the beginning of CLAUDE.md to ensure AI retrieves history at session start:
# โ ๏ธ 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**
Auto-Store Rules
Add these rules to make AI automatically store memories at key points:
# 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"
}
}
Retrieval Triggers
- Encountering similar issues โ Search for existing solutions first
- Before tech decisions โ Check previous decision records
- Continuing previous work โ Retrieve last session summary
### 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"
๐ Retrieval Algorithm
Memory Pulse uses a 3-level cascade retrieval strategy:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 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 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Why this approach?
- Precision first: Exact matches are faster and more accurate
- Graceful degradation: Falls back to broader search when needed
- No false positives: Semantic search is last resort, not default
๐ Memory Types
| Type | Use Case | Required Fields |
|---|---|---|
decision | Architectural choices | question, options, chosen, reason |
solution | Problem fixes | problem, rootCause, solution |
session | Session summaries | summary, decisions, nextSteps |
code | Code implementations | content, artifacts |
error | Error records | content, stackTrace |
config | Configuration info | content, settings |
๐ฅ๏ธ Web Dashboard
Memory Pulse includes a beautiful Web Dashboard for visualizing and managing your memories.
Features
| Feature | Description |
|---|---|
| Memory Management | Browse, search, and create memories with a modern UI |
| Timeline View | See your memory evolution over time |
| Relationship Graph | Interactive visualization of memory connections |
| Project Filtering | Switch between projects with one click |
| Full-text Search | Quickly find any memory |
๐ Deployment Guide
Choose the deployment scenario that fits your needs:
Scenario 1: SQLite (Local Personal Use)
Best for: Individual developers, lightweight usage, getting started quickly.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Your Local Machine โ
โ โ
โ Claude Code โ MCP Server โ
โ โ โ
โ ~/.emp/memory.db โ
โ โ โ
โ Web Dashboard โ
โ โ โ
โ http://localhost:3001 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Step 1: Configure MCP Server
Add to your Claude MCP config (~/.claude.json or .mcp.json):
{
"mcpServers": {
"memory-pulse": {
"command": "npx",
"args": ["-y", "memory-pulse-mcp-server"]
}
}
}
Step 2: Restart Claude to activate the MCP Server.
Step 3: Start Web Dashboard locally
# 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
Step 4: Open http://localhost:3001 in your browser.
How it works: When MCP Server starts, it writes its configuration to
~/.emp/runtime-config.json. The API server reads this file and automatically connects to the same SQLite database.
Scenario 2: PostgreSQL (Team / Production Use)
Best for: Team collaboration, multi-device access, production deployment.
โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
โ User A (Local) โ โ User B (Local) โ
โ MCP Server โ โ MCP Server โ
โโโโโโโโโโฌโโโโโโโโโโ โโโโโโโโโโฌโโโโโโโโโโ
โ โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ PostgreSQL Database โ
โ (Shared data storage) โ
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโ
โ Web Dashboard โ
โ (Deployed on server) โ
โ http://your-server:3001 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Step 1: Set up PostgreSQL database
# 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
Step 2: Configure MCP Server for each user
Add to Claude MCP config (~/.claude.json or .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"
}
}
}
}
Step 3: Deploy Web Dashboard on your server
# 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
Step 4: Access Web Dashboard at http://your-server:3001
Key point: Both MCP Server and Web Dashboard must use the same DATABASE_URL to see the same data.
Configuration Priority
The system reads configuration in this order (first found wins):
- Environment variables -
MEMORY_STORAGE,DATABASE_URL,MEMORY_DB_PATH - Runtime config file -
~/.emp/runtime-config.json(written by MCP Server) - Default values - SQLite at
~/.emp/memory.db
Docker Deployment (Production)
For production environments, you can use 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
Screenshots
Dashboard Home

Relationship Graph

๐๏ธ Architecture
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 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) โ โ
โ โโโโโโโโโโโโโโโโโโโ โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Components
| Component | Description | Technology |
|---|---|---|
| MCP Server | Core memory operations via MCP protocol | Node.js, TypeScript |
| Storage Layer | Flexible storage backends | SQLite / PostgreSQL |
| API Server | RESTful API for web access | Express.js |
| Web Dashboard | Visual management interface | Next.js 15, React 19 |
๐ Security & Privacy
- Local-first - All data stored locally in SQLite, no cloud dependency
- Your Data - Database file is yours, backup/migrate anytime
- No Telemetry - Zero data collection or phone-home
- Project Isolation - Memories isolated by projectId
๐บ๏ธ Roadmap
- MCP Server core functionality
- SQLite local storage
- PostgreSQL cloud support
- Multi-level retrieval (Exact + Full-text)
- Decision/Solution/Session structured storage
- Web Dashboard for visualization
- CLI tool for manual operations
- Semantic search (Embedding)
- Team collaboration features
๐ Star History
๐ค Contributing
Issues and Pull Requests are welcome!
# Development
git clone https://github.com/jiahuidegit/memory-mcp-server.git
cd memory-mcp-server
pnpm install
pnpm build
pnpm test
๐ License
This project is licensed under the MIT License.
โญ If you find this project helpful, please give it a star!
๐ค Feel free to open issues for questions or submit PRs for improvements!
