npm package: @iflow-mcp/jiahuidegit-memory-pulse-mcp-server
Description: Memory Pulse - 精准、结构化的 AI 上下文记忆系统 MCP Server
Author: jiahui
Latest version: 0.1.16

# Memory Pulse MCP Server

[![GitHub Stars](https://img.shields.io/github/stars/jiahuidegit/memory-mcp-server?style=social)](https://github.com/jiahuidegit/memory-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
[![npm version](https://img.shields.io/npm/v/memory-pulse-mcp-server.svg)](https://www.npmjs.com/package/memory-pulse-mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/memory-pulse-mcp-server.svg)](https://www.npmjs.com/package/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](https://github.com/jiahuidegit/memory-mcp-server)!** Your support helps us improve!

[English](https://github.com/jiahuidegit/memory-mcp-server#readme) | [中文](https://github.com/jiahuidegit/memory-mcp-server/blob/main/README_CN.md)

---

## What's New

### v0.1.16 - Smart Retrieval with Auto-Degradation

This release introduces a major upgrade to the retrieval engine. **Memory Pulse now guarantees you always get results** -- even when your query keywords don't exactly match stored content.

**Multi-Dimension Search** -- Searches across 5 dimensions simultaneously: `projectId`, `summary`, `fullText`, `tags`, and `keywords`. Any keyword matching any dimension counts as a hit.

**Smart Auto-Degradation** -- When no results are found, the engine automatically relaxes search conditions in two stages:

```
Stage 1: Query matches nothing?
         -> Remove keywords, return latest memories for the project

Stage 2: Still nothing?
         -> Remove project filter, search globally
```

This means `mpulse_recall` with a `projectId` will **never return empty** as long as that project has any memories stored -- no matter what query you use.

**Other improvements:**
- Auto-relationship building: new memories automatically link to related existing memories
- Improved PostgreSQL storage: `multiDimensionSearch` replaces legacy search methods
- Fixed `storeSolution` tags handling for PostgreSQL

---

## 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** | Multi-dimension + auto-degradation | Semantic only | Semantic + Temporal | Semantic only |
| **Never Empty Recall** | Yes (auto-degradation) | No | No | No |
| **Decision Tracking** | Forced structured fields | - | - | - |
| **Auto-Relationships** | Built-in | - | - | - |
| **Relationship Graph** | Built-in | - | Built-in | - |
| **Timeline View** | Built-in | - | Built-in | - |
| **MCP Native** | Yes | - | - | - |
| **Local-first** | SQLite + PostgreSQL | Cloud-dependent | Cloud-dependent | Varies |
| **Zero Config** | Yes | - | - | - |

---

## Features

- **Always Gets Results** - Smart auto-degradation ensures you never get empty recalls
- **Multi-Dimension Search** - Searches across projectId, summary, fullText, tags, and keywords simultaneously
- **Complete Context Preservation** - No compression, no information loss
- **Structured Memory Types** - Decision / Solution / Session / Code / Error / Config
- **Auto-Relationship Building** - New memories automatically link to related existing ones
- **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 by default, your data stays with you
- **PostgreSQL Support** - Scale to cloud for team usage
- **Zero Config** - Works out of the box with `npx`

---

## Quick Start

### Option 1: Run with npx (Recommended)

```bash
npx memory-pulse-mcp-server
```

### Option 2: Global Installation

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

### Option 3: Build from Source

```bash
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

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

### Check current version

```bash
npm list -g memory-pulse-mcp-server
```

---

## MCP Client Configuration

### Claude Code

Create `.mcp.json` in your project directory:

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

Or global configuration at `~/.claude/mcp.json`:

```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`

```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 | `./memory.db` |
| `DATABASE_URL` | PostgreSQL connection string (required for postgresql) | - |

### SQLite Storage (Default)

Zero configuration, works out of the box:

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

### Custom SQLite Path

```json
{
  "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:

```json
{
  "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**: PostgreSQL storage requires `@prisma/client`. Install it manually if needed:
> ```bash
> npm install @prisma/client
> ```

---

## 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)
```

---

## Retrieval Algorithm

Memory Pulse uses a **multi-dimension search with smart auto-degradation**:

```
┌──────────────────────────────────────────────────────┐
│                     User Query                        │
│            (query + projectId + filters)              │
└──────────────────────┬───────────────────────────────┘
                       ▼
┌──────────────────────────────────────────────────────┐
│  Multi-Dimension Search (< 100ms)                     │
│  Searches 5 dimensions simultaneously:               │
│  projectId | summary | fullText | tags | keywords    │
│  Any keyword matching any dimension = hit            │
└──────────────────────┬───────────────────────────────┘
                       ▼ (if 0 results)
┌──────────────────────────────────────────────────────┐
│  Auto-Degradation Stage 1                             │
│  Remove query keywords, keep projectId               │
│  -> Returns latest memories for the project          │
└──────────────────────┬───────────────────────────────┘
                       ▼ (if still 0 results)
┌──────────────────────────────────────────────────────┐
│  Auto-Degradation Stage 2                             │
│  Remove projectId filter, search globally            │
│  -> Returns latest memories across all projects      │
└──────────────────────┬───────────────────────────────┘
                       ▼ (optional, if vector available)
┌──────────────────────────────────────────────────────┐
│  Semantic Search Fallback                             │
│  Embedding similarity for fuzzy matching             │
└──────────────────────────────────────────────────────┘
```

**Why this approach?**

- **Never empty**: Smart degradation guarantees results when memories exist
- **Precision first**: Multi-dimension exact matching before relaxing conditions
- **Graceful fallback**: Progressively broader search, not a sudden jump to fuzzy matching
- **Works with any language**: No tokenizer dependency, LIKE-based matching works with Chinese, English, and mixed content

---

## 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 |

---

## Security & Privacy

1. **Local-first** - All data stored locally in SQLite, no cloud dependency
2. **Your Data** - Database file is yours, backup/migrate anytime
3. **No Telemetry** - Zero data collection or phone-home
4. **Project Isolation** - Memories isolated by projectId

---

## Web Dashboard (Optional)

Memory Pulse includes an optional Web Dashboard for visualizing and managing your memories.

Check out the full project repository for the Web Dashboard:
👉 [https://github.com/jiahuidegit/memory-mcp-server](https://github.com/jiahuidegit/memory-mcp-server)

Features:
- Memory management with modern UI
- Timeline view
- Relationship graph visualization
- Project filtering
- Full-text search

---

## Roadmap

- [x] MCP Server core functionality
- [x] SQLite local storage
- [x] PostgreSQL cloud support
- [x] Multi-dimension retrieval with smart auto-degradation
- [x] Decision/Solution/Session structured storage
- [x] Auto-relationship building between memories
- [x] Web Dashboard for visualization
- [ ] CLI tool for manual operations
- [ ] Semantic search (Embedding)
- [ ] Team collaboration features

---

## Star History

<a href="https://star-history.com/#jiahuidegit/memory-mcp-server&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=jiahuidegit/memory-mcp-server&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=jiahuidegit/memory-mcp-server&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=jiahuidegit/memory-mcp-server&type=Date" />
 </picture>
</a>

---

## Contributing

Issues and Pull Requests are welcome!

```bash
# 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](LICENSE).

---

**If you find this project helpful, please give it a star!**

**Feel free to open issues for questions or submit PRs for improvements!**