# https://github.com/doobidoo/mcp-memory-service 项目说明书
生成时间：2026-05-15 14:48:14 UTC
## 目录
- [Overview and Key Concepts](#overview)
- [Installation and Setup](#installation)
- [Quick Start Guide](#quickstart)
- [System Architecture](#architecture)
- [Storage Backends](#storage-backends)
- [Knowledge Graph and Entity Extraction](#knowledge-graph)
- [Memory Consolidation Engine](#consolidation-engine)
- [Quality Scoring System](#quality-scoring)
- [REST API Reference](#rest-api)
- [Agent Framework Integration](#agent-frameworks)
## Overview and Key Concepts
### 相关页面
相关主题：[System Architecture](#architecture), [Installation and Setup](#installation), [Quick Start Guide](#quickstart)
Relevant Source Files
以下源码文件用于生成本页说明：
- [README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/README.md)
- [src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)
- [src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
- [src/mcp_memory_service/server/utils/response_limiter.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)
- [claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)
- [claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)
- [scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)
# Overview and Key Concepts
The MCP Memory Service is a semantic memory storage and retrieval system designed for AI-assisted development workflows. It provides persistent memory capabilities for Claude Code and other MCP-compatible clients, enabling intelligent context retention across development sessions.
## What is MCP Memory Service?
MCP Memory Service solves the context loss problem in AI-assisted development by maintaining a persistent, searchable store of development decisions, architectural choices, and project knowledge. When you work on a project, the service captures important decisions and makes them available in future sessions.
资料来源：[README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/README.md)
## Architecture Overview
The system follows a layered architecture with clear separation between storage, API, and client integration layers.
```mermaid
graph TD
A[Claude Code / MCP Clients] -->|MCP Protocol| B[MCP Server Layer]
B --> C[REST API Layer]
C --> D[Service Layer]
D --> E[Storage Backend]
E -->|SQLite-vec| F[Local Vector Storage]
E -->|Cloudflare| G[D1 + Vectorize]
E -->|Hybrid| H[Combined Approach]
I[Web Dashboard] -->|HTTP| C
J[Claude Hooks] -->|Session Events| B
```
### Supported Storage Backends
| Backend | Description | Use Case |
|---------|-------------|----------|
| SQLite-vec | Local vector storage with SQLite | Single-machine deployments |
| Cloudflare D1 + Vectorize | Cloud-hosted serverless | Multi-device, global access |
| Hybrid | Combined local and cloud | Redundancy and performance |
资料来源：[src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)
## Core Components
### 1. MCP Server
The MCP Server implements the Model Context Protocol, providing tools and prompts for memory operations. It handles tool execution, prompt management, and bidirectional communication with MCP clients.
**Key Tools:**
- `store_memory` - Store new memories with automatic embedding generation
- `search_memories` - Semantic similarity search using embeddings
- `retrieve_memory` - Retrieve specific memory by content hash
- `delete_memory` - Remove memory and associated embeddings
- `list_memories` - List all memories with pagination
**Key Prompts:**
- `knowledge_retrieval` - Structured memory retrieval with relevance ranking
- `memory_summary` - Generate summaries of stored memories
- `knowledge_export` - Export memories in various formats
- `memory_cleanup` - Identify and remove duplicates
资料来源：[src/mcp_memory_service/server_impl.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.py)
### 2. REST API Layer
The REST API provides HTTP endpoints for direct access to memory operations, useful for integrations and the web dashboard.
```mermaid
graph LR
A[Memory Management] -->|POST /api/memories| B[Store]
A -->|GET /api/memories| C[List]
A -->|GET /api/memories/{hash}| D[Retrieve]
A -->|DELETE /api/memories/{hash}| E[Delete]
F[Search Operations] -->|POST /api/search| G[Semantic Search]
F -->|GET /api/search/similar/{hash}| H[Similar Search]
I[Real-time Events] -->|GET /api/events| J[SSE Stream]
I -->|GET /api/events/stats| K[Statistics]
```
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/memories` | POST | Store a new memory with automatic embedding generation |
| `/api/memories` | GET | List all memories with pagination support |
| `/api/memories/{hash}` | GET | Retrieve a specific memory by content hash |
| `/api/memories/{hash}` | DELETE | Delete a memory and its embeddings |
| `/api/search` | POST | Semantic similarity search using embeddings |
| `/api/search/similar/{hash}` | GET | Find memories similar to a specific one |
| `/api/events` | GET | Subscribe to real-time memory events stream |
资料来源：[src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
### 3. Web Dashboard
The built-in web interface provides:
- Interactive API documentation (Swagger UI and ReDoc)
- Real-time statistics display
- SSE testing interface
- Health monitoring
资料来源：[src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
## Key Features
### Semantic Search with Embeddings
The service uses the `all-MiniLM-L6-v2` embedding model to convert memory content into vector representations. This enables semantic similarity search that understands meaning rather than just keyword matching.
**Performance Characteristics:**
| Metric | Value |
|--------|-------|
| First call latency | ~50ms (includes storage initialization) |
| Subsequent calls | ~5-10ms (connection reused) |
| Memory overhead | <10MB |
| Cost at $0.15/1M tokens | $16.43/year per 10-user deployment |
资料来源：[src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)
### Response Size Limiter
To prevent context window overflow in LLM clients, the service includes a response limiter that truncates large responses at memory boundaries. This ensures that large memory retrieval operations don't crash Claude or other LLM clients.
**Configuration:**
| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `MCP_MAX_RESPONSE_CHARS` | 0 (unlimited) | Maximum characters in responses |
资料来源：[src/mcp_memory_service/server/utils/response_limiter.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)
### Claude Code Integration
The service provides deep integration with Claude Code through hooks and slash commands.
**Available Commands:**
| Command | Purpose |
|---------|---------|
| `/memory-store` | Store important decisions and context |
| `/memory-recall` | Retrieve memories using natural language |
| `/memory-search` | Search by tags and content keywords |
| `/memory-context` | Capture current session context |
| `/memory-health` | Check service health and statistics |
资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)
**Automatic Hooks:**
- **Session Start**: Load relevant project memories when Claude Code starts
- **Session End**: Store insights and decisions from completed sessions
- **Memory Retrieval**: On-demand memory access during conversations
- **Permission Requests**: Automated handling of MCP permission requests
资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)
## Memory Types Taxonomy
The service organizes memories into a standardized taxonomy:
| Category | Types |
|----------|-------|
| Content Types | note, reference, document, guide |
| Activity Types | session, implementation, analysis |
This standardized taxonomy helps with memory organization and retrieval. The maintenance scripts can consolidate fragmented types into this standardized set.
资料来源：[scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)
## Data Model
Each memory in the system has the following structure:
```json
{
"content": "Memory content here",
"content_hash": "sha256hash",
"tags": ["tag1", "tag2"],
"created_at": 1673545200.0,
"updated_at": 1673545200.0,
"memory_type": "note",
"metadata": {},
"export_source": "machine-name"
}
```
| Field | Type | Description |
|-------|------|-------------|
| content | string | The actual memory content |
| content_hash | string | SHA256 hash of content for deduplication |
| tags | array | User-defined tags for categorization |
| created_at | float | Unix timestamp of creation |
| updated_at | float | Unix timestamp of last update |
| memory_type | string | Standardized type classification |
| metadata | object | Additional metadata storage |
| export_source | string | Source machine identifier |
## Synchronization and Backup
### Export/Import
Memories can be exported and imported in JSON format for backup and migration purposes:
- **Export**: ~1000 memories/second
- **Import**: ~500 memories/second with deduplication
- **File Size**: ~1KB per memory
### Litestream Integration
For real-time replication, the service supports Litestream configuration, providing continuous backup to object storage.
资料来源：[src/mcp_memory_service/sync/litestream_config.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/sync/litestream_config.py)
## Maintenance Tools
The service includes several maintenance scripts:
| Script | Purpose |
|--------|---------|
| `check_memory_types.py` | Analyze type distribution and fragmentation |
| `consolidate_memory_types.py` | Consolidate fragmented types into standardized taxonomy |
| `export_memories.py` | Export memories to JSON format |
| `import_memories.py` | Import memories from JSON with deduplication |
资料来源：[scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)
## Installation Methods
### Python Package Installation
```bash
pip install mcp-memory-service
```
### Claude Code Integration
```bash
cd claude-hooks
python install_hooks.py --natural-triggers
```
资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)
## Summary
MCP Memory Service provides a comprehensive solution for maintaining persistent, searchable memory across AI-assisted development sessions. Its layered architecture supports multiple storage backends, while deep Claude Code integration enables seamless workflow integration. The system prioritizes reliability through response limiting, data deduplication, and maintenance tools that keep the memory store organized and efficient.
---
## Installation and Setup
### 相关页面
相关主题：[Quick Start Guide](#quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [install.py](https://github.com/doobidoo/mcp-memory-service/blob/main/install.py)
- [scripts/installation/install.py](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/installation/install.py)
- [.env.example](https://github.com/doobidoo/mcp-memory-service/blob/main/.env.example)
- [pyproject.toml](https://github.com/doobidoo/mcp-memory-service/blob/main/pyproject.toml)
# Installation and Setup
## Overview
The MCP Memory Service provides a comprehensive installation framework supporting multiple deployment scenarios including pip installation, Claude Code integration, OpenCode plugin support, and standalone HTTP server deployment. The setup system is designed to be modular, allowing users to install only the components they need while maintaining cross-platform compatibility across Windows, macOS, and Linux environments.
## System Requirements
### Prerequisites
The installation system requires several external dependencies that must be present before deployment:
| Dependency | Purpose | Platform-Specific Notes |
|------------|---------|------------------------|
| Python 3.10+ | Runtime environment | Required on all platforms |
| Node.js | Hooks execution | Required for Claude Code hooks |
| `jq` | Status line features | macOS: `brew install jq`; Linux: `sudo apt install jq`; Windows: `choco install jq` |
| pip | Package management | Included with Python 3.10+ |
The dependency checking system (`src/mcp_memory_service/dependency_check.py`) validates all required dependencies during initialization and provides clear guidance if any are missing.
### Environment Requirements
The service requires specific directory structures and environment variables:
```bash
# Standard data directory
~/.local/share/mcp-memory/
# Database file
~/.local/share/mcp-memory/sqlite_vec.db
# Configuration directory
~/.claude/hooks/config.json # For Claude Code integration
```
## Installation Methods
### Method 1: Pip Installation
The primary installation method uses pip to install the `mcp-memory-service` package:
```bash
pip install mcp-memory-service
```
The `pyproject.toml` file defines all package dependencies and metadata for PyPI distribution. This installation provides:
- Core memory service library
- HTTP server implementation
- API endpoints
- CLI tools
资料来源：[pyproject.toml]()
### Method 2: Standalone HTTP Server Installation
For HTTP server deployment, the installation script provides a guided setup process:
```bash
# From the repository root
python scripts/installation/install.py
# With specific options
python scripts/installation/install.py --install-claude-commands # Install Claude commands
python scripts/installation/install.py --skip-claude-commands-prompt # Skip command prompt
```
The installer performs the following operations:
1. Validates system prerequisites
2. Installs the `mcp-memory-service` package
3. Creates required directories
4. Configures environment variables
5. Sets up systemd services (on Linux)
6. Optionally installs Claude Code commands
资料来源：[scripts/installation/install.py]()
### Method 3: Claude Code Hooks Installation
Claude Code hooks provide automatic memory awareness and context injection. The unified installer supports multiple installation modes:
```bash
cd claude-hooks
# Install Natural Memory Triggers (recommended)
python install_hooks.py --natural-triggers
# OR install basic memory awareness hooks
python install_hooks.py --basic
```
The hooks system consists of several components:
| Component | File | Purpose |
|-----------|------|---------|
| Session Start Hook | `session-start.js` | Loads relevant memories when Claude Code starts |
| Session End Hook | `session-end.js` | Stores session insights and decisions |
| Memory Retrieval | `memory-retrieval.js` | On-demand memory retrieval |
| Permission Request | `permission-request.js` | MCP server permission automation |
资料来源：[claude-hooks/README.md]()
### Method 4: Claude Commands Installation
For Claude Code CLI integration, custom commands can be installed:
```bash
# Automatic installation during main setup
python scripts/installation/install.py --install-claude-commands
# Manual installation
python scripts/claude_commands_utils.py
# Test prerequisites
python scripts/claude_commands_utils.py --test
# Uninstall
python scripts/claude_commands_utils.py --uninstall
```
Commands are installed to `~/.claude/commands/` and provide:
- `/memory-save` - Save memories with tags
- `/memory-recall` - Time-based memory retrieval
- `/memory-search` - Tag and content search
- `/memory-context` - Session context integration
- `/memory-health` - Service health check
资料来源：[claude_commands/README.md]()
### Method 5: OpenCode Plugin Installation
The OpenCode plugin provides memory awareness for the OpenCode editor:
```bash
# Install plugin file
mkdir -p ~/.config/opencode/plugins
cp opencode/memory-plugin.js ~/.config/opencode/plugins/
# Install example configuration
cp opencode/memory-plugin.config.example.json ~/.config/opencode/memory-plugin.json
```
资料来源：[opencode/README.md]()
## Environment Configuration
### Environment Variables
The `.env.example` file provides configuration templates:
```bash
# MCP Memory Service Configuration
MCP_API_KEY=your-api-key-here
MCP_MEMORY_ENDPOINT=https://localhost:8443
MCP_MEMORY_TIMEOUT_MS=30000
MCP_MEMORY_LOAD_TIMEOUT_MS=10000
```
### Configuration Hierarchy
The OpenCode plugin demonstrates the configuration precedence system:
```mermaid
graph TD
A[Config Options] --> B[Environment Variables]
A --> C[Default Config File]
B --> D[OPENCODE_MEMORY_ENDPOINT]
B --> E[OPENCODE_MEMORY_API_KEY]
B --> F[OPENCODE_MEMORY_TIMEOUT_MS]
C --> G[~/.config/opencode/memory-plugin.json]
```
Configuration order of precedence (highest to lowest):
1. Explicit plugin options
2. Environment variables
3. User config file (`~/.config/opencode/memory-plugin.json`)
4. Project-local config (`.opencode/memory-plugin.json`)
资料来源：[opencode/README.md]()
## HTTP Server Deployment
### Service Setup on Linux/macOS
The Litestream configuration system supports streaming SQLite replication for data durability:
```bash
# Install Litestream
curl -LsS https://github.com/benbjohnson/litestream/releases/latest/download/litestream-linux-amd64.tar.gz | tar -xzf -
sudo mv litestream /usr/local/bin/
# Generate configuration
python scripts/sync/litestream_config.py
```
### Systemd Service Configuration
Production deployment uses systemd for service management:
```bash
# Start the service
systemctl --user start mcp-memory-http.service
# Enable on boot
systemctl --user enable mcp-memory-http.service
# Check status
systemctl --user status mcp-memory-http.service
```
资料来源：[src/mcp_memory_service/sync/litestream_config.py]()
### Windows Service Setup
For Windows deployment, a LaunchAgent plist configuration is provided:
```xml
Label
com.mcp-memory-service
ProgramArguments
/local/bin/litestream
replicate
-config
{config_path}
RunAtLoad
```
资料来源：[src/mcp_memory_service/sync/litestream_config.py]()
## Data Synchronization
### Database Export/Import
For cross-machine synchronization, the sync scripts provide export and import functionality:
```bash
# Export memories to JSON
python scripts/sync/export_memories.py --output ./memories_export.json
# Import memories from JSON
python scripts/sync/import_memories.py --input ./memories_export.json
```
The export format preserves all memory metadata:
```json
{
"export_metadata": {
"source_machine": "machine-name",
"export_timestamp": "2025-08-12T10:30:00Z",
"total_memories": 450,
"database_path": "/path/to/sqlite_vec.db"
},
"memories": [
{
"content": "Memory content",
"content_hash": "sha256hash",
"tags": ["tag1", "tag2"],
"created_at": 1673545200.0,
"memory_type": "note"
}
]
}
```
Deduplication is based on content hash during import.
资料来源：[scripts/sync/README.md]()
## Maintenance Procedures
### Database Type Consolidation
Over time, memory types may become fragmented. The consolidation script standardizes the taxonomy:
```bash
# Preview changes (safe, read-only)
python scripts/maintenance/consolidate_memory_types.py --dry-run
# Execute consolidation
python scripts/maintenance/consolidate_memory_types.py
# With custom mapping
python scripts/maintenance/consolidate_memory_types.py --config custom_mappings.json
```
The standard 24-type taxonomy includes:
| Category | Types |
|----------|-------|
| Content Types | `note`, `reference`, `document`, `guide` |
| Activity Types | `session`, `implementation`, `analysis` |
资料来源：[scripts/maintenance/README.md]()
## Verification
After installation, verify the setup with these checks:
```bash
# Verify Claude hooks installation
claude --debug hooks
# Run integration tests
cd ~/.claude/hooks && node tests/integration-test.js
# Test API health
curl -k https://your-endpoint:8443/api/health
# Verify database
sqlite3 ~/.local/share/mcp-memory/sqlite_vec.db "SELECT COUNT(*) FROM memories;"
```
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| Hooks not detected | Check `ls ~/.claude/settings.json`; reinstall if missing |
| JSON parse errors | Update to latest version |
| Connection failed | Verify endpoint with `curl -k https://your-endpoint:8443/api/health` |
| Wrong directory | Move `~/.claude-code/hooks/*` to `~/.claude/hooks/` |
| Missing `jq` | Install per platform instructions in prerequisites |
### Debug Mode
Enable detailed logging for troubleshooting:
```bash
# Claude Code debug mode
claude --debug hooks
# Test individual hooks
node ~/.claude/hooks/core/session-start.js
```
## PyPI Placeholder Packages
For users who may install the wrong package name, placeholder packages redirect to the correct installation:
```bash
# These packages emit deprecation warnings and redirect to mcp-memory-service
pip install mcp-memory
pip install memory-service
pip install agent-mem
```
资料来源：[tools/pypi-placeholders/README.md]()
## Architecture Overview
```mermaid
graph TD
subgraph "Installation Methods"
A[Pip Installation] --> E[Core Service]
B[Claude Hooks] --> F[Memory Awareness]
C[Claude Commands] --> G[CLI Integration]
D[OpenCode Plugin] --> H[Editor Integration]
end
subgraph "Runtime Components"
E --> I[HTTP Server]
I --> J[API Endpoints]
J --> K[Memory Storage]
K --> L[sqlite_vec]
end
subgraph "Data Layer"
L --> M[Local Storage]
L --> N[LitekStream Sync]
end
---
## Quick Start Guide
### 相关页面
相关主题：[Overview and Key Concepts](#overview), [REST API Reference](#rest-api), [Agent Framework Integration](#agent-frameworks)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
- [src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)
- [claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)
- [claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)
- [scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)
# Quick Start Guide
## Overview
The MCP Memory Service Quick Start Guide provides developers and users with a streamlined path to deploy and begin using the persistent semantic memory system for AI agents. This guide covers installation methods, initial configuration, core functionality verification, and essential commands for day-to-day operations.
The service serves as a centralized memory backend that stores, retrieves, and manages semantic memories with automatic embedding generation. It supports multiple deployment configurations including local SQLite-vec storage, Cloudflare D1 + Vectorize for cloud deployments, and hybrid configurations for distributed workflows across multiple machines.
## Prerequisites
Before beginning the installation, ensure your development environment meets the following requirements:
| Requirement | Minimum Version | Notes |
|-------------|-----------------|-------|
| Python | 3.10+ | Required for core service |
| Node.js | 16+ | Required for hooks execution |
| SQLite | 3.35+ | Bundled with Python |
| jq | 1.6+ | Required for statusLine feature |
| Claude Code CLI | Latest | Optional, for Claude command integration |
### Installing jq (Required for StatusLine Feature)
```bash
# macOS
brew install jq
# Linux (Ubuntu/Debian)
sudo apt install jq
# Windows
choco install jq
```
## Installation Methods
### Automatic Installation (Recommended)
The recommended approach uses the unified installer which handles all components:
```bash
cd claude-hooks
python install_hooks.py
```
The installer supports multiple installation modes:
| Mode | Command | Description |
|------|---------|-------------|
| Full Installation | `python install_hooks.py` | Installs all features including basic hooks and natural triggers |
| Basic Only | `python install_hooks.py --basic` | Installs memory hooks only |
| Natural Triggers | `python install_hooks.py --natural-triggers` | Installs natural memory triggers only |
### MCP Memory Service Installation
For the core memory service with HTTP server:
```bash
# Install with commands (will prompt if Claude Code CLI is detected)
python scripts/installation/install.py
# Force install commands
python scripts/installation/install.py --install-claude-commands
# Skip command installation prompt
python scripts/installation/install.py --skip-claude-commands-prompt
```
## Initial Configuration
### Claude Desktop Configuration
To integrate MCP Memory Service with Claude Desktop, create or modify the Claude Desktop configuration file. The configuration path varies by operating system:
- **macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
Example configuration structure:
```json
{
"mcpServers": {
"mcp-memory-service": {
"command": "python",
"args": [
"-m",
"mcp_memory_service",
"server"
],
"env": {
"MCP_MEMORY_DB_PATH": "~/.local/share/mcp-memory/sqlite_vec.db"
}
}
}
}
```
### Environment Variables
The service recognizes several environment variables for configuration:
| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_MEMORY_DB_PATH` | `~/.local/share/mcp-memory/sqlite_vec.db` | Database storage path |
| `MCP_MEMORY_BACKEND` | `sqlite_vec` | Storage backend type |
| `MCP_MEMORY_PORT` | `8443` | HTTP server port |
| `MCP_MEMORY_API_KEY` | None | Optional API key authentication |
### Backend Configuration Options
The service supports multiple backend configurations:
| Backend | Use Case | Configuration Value |
|---------|----------|---------------------|
| SQLite-vec | Local development, single machine | `sqlite_vec` or `sqlite-vec` |
| Cloudflare D1 | Cloud deployment | `cloudflare` |
| Hybrid | Multi-machine sync | `hybrid` |
资料来源：[src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
## Starting the Service
### HTTP Server Mode
Start the HTTP server for REST API access:
```bash
python -m mcp_memory_service server
```
The server provides an interactive dashboard at the root URL (`/`) displaying:
- Total memory count
- Active embedding model
- Server health status
- Response time metrics
### MCP Server Mode
Start as an MCP server for Claude integration:
```bash
python -m mcp_memory_service mcp
```
### Service Health Verification
Verify the installation by checking service health:
```bash
curl -k https://localhost:8443/api/health
```
Expected response includes:
- `backend`: Current storage backend (e.g., `sqlite_vec`)
- `count`: Total number of stored memories
- `status`: Service health status
## Core API Endpoints
The service exposes RESTful endpoints for memory operations:
资料来源：[src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
### Memory Management Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/memories` | Store a new memory with automatic embedding |
| GET | `/api/memories` | List all memories with pagination |
| GET | `/api/memories/{hash}` | Retrieve specific memory by content hash |
| DELETE | `/api/memories/{hash}` | Delete a memory and its embeddings |
### Search Operations
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/search` | Semantic similarity search using embeddings |
| GET | `/api/search/tags/{tag}` | Find memories by specific tag |
| GET | `/api/search/similar/{hash}` | Find memories similar to a specific one |
### Real-time Events
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/events` | Subscribe to real-time memory event stream (SSE) |
| GET | `/api/events/stats` | View SSE connection statistics |
### API Documentation
Interactive API documentation is available at:
- **Swagger UI**: `/api/docs`
- **ReDoc**: `/api/redoc`
## Claude Commands Integration
After installation, several slash commands become available within Claude Code:
资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)
### Available Commands
#### `/memory-store` - Store New Memories
Store a new memory with automatic content hashing and embedding generation.
```bash
claude /memory-store "Implemented OAuth 2.1 authentication for improved security"
claude /memory-store "Refactored storage backend to support sqlite-vec for performance"
```
#### `/memory-recall` - Time-based Memory Retrieval
Retrieve memories using natural language time expressions.
```bash
claude /memory-recall "what did we decide about the database last week?"
claude /memory-recall "yesterday's architectural discussions"
```
#### `/memory-search` - Tag and Content Search
Search through stored memories using tags, content keywords, and semantic similarity.
```bash
claude /memory-search --tags "architecture,database"
claude /memory-search "SQLite performance optimization"
```
#### `/memory-context` - Session Context Integration
Capture the current conversation and project context as a memory.
```bash
claude /memory-context
claude /memory-context --summary "Architecture planning session"
```
#### `/memory-health` - Service Health Check
Check the health and status of the MCP Memory Service.
```bash
claude /memory-health
claude /memory-health --detailed
```
## Claude Hooks Configuration
The hooks system provides automatic memory capture during Claude Code sessions:
资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)
### Hook Types
| Hook | Trigger | Action |
|------|---------|--------|
| `session-start` | Claude Code launch | Load relevant project memories |
| `session-end` | Claude Code exit | Store insights and decisions |
| `auto-capture` | Automatic capture trigger | Capture important context |
| `mid-conversation` | Periodic intervals | Summarize and store progress |
### Configuration File
Edit `~/.claude/hooks/config.json` to customize hook behavior:
```json
{
"memoryService": {
"endpoint": "https://your-server:8443",
"apiKey": "optional-api-key"
},
"hooks": {
"verbose": true,
"showMemoryDetails": false,
"cleanMode": false,
"autoCapture": true,
"forceRemember": "#remember",
"forceSkip": "#skip",
"applyTo": ["auto-capture", "session-start", "mid-conversation", "session-end"]
}
}
```
### Verbosity Levels
| Level | Settings | Output |
|-------|----------|--------|
| Normal | `verbose: true`, others `false` | Essential information only |
| Detailed | `showMemoryDetails: true` | Includes memory scoring details |
| Clean | `cleanMode: true` | Minimal output, success/error only |
| Silent | `verbose: false` | Background operation only |
## Multi-Machine Synchronization
For users working across multiple machines, the service supports database synchronization:
资料来源：[scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)
### Export/Import Workflow
```mermaid
graph TD
A[Machine A] -->|export| B[JSON File]
B -->|import| C[Machine B]
B -->|import| D[Machine C]
E[Central Database] -->|replicate| A
E -->|replicate| C
```
### Export Command
```bash
python scripts/sync/export_memories.py \
--source-db ~/.local/share/mcp-memory/sqlite_vec.db \
--output ~/memories-export.json \
--machine-name "workstation-1"
```
### Import Command
```bash
python scripts/sync/import_memories.py \
--input ~/memories-export.json \
--target-db ~/.local/share/mcp-memory/sqlite_vec.db
```
### Deduplication
Memories are deduplicated based on content hash during import:
- **Same content hash**: Treated as duplicate, skipped
- **Different content hash**: Imported as unique memory
- **Original timestamps**: Preserved from source
- **Source machine tags**: Added automatically for tracking
### Litestream Configuration
For continuous database replication, configure Litestream:
```yaml
dbs:
- path: ~/.local/share/mcp-memory/sqlite_vec.db
replicas:
- url: s3://your-bucket/memory-db
sync-interval: 1s
```
## Verification
### Verify Hook Installation
```bash
claude --debug hooks
```
Expected output: `Found 1 hook matchers in settings`
### Run Integration Tests
```bash
cd ~/.claude/hooks
node tests/integration-test.js
```
Expected: All 14 integration tests pass
### Test API Endpoints
```bash
# Health check
curl -s https://localhost:8443/api/health | jq
# Store a test memory
curl -X POST https://localhost:8443/api/memories \
-H "Content-Type: application/json" \
-d '{"content": "Test memory from quick start", "tags": ["test"]}'
# Search memories
curl -X POST https://localhost:8443/api/search \
-H "Content-Type: application/json" \
-d '{"query": "test", "limit": 5}'
```
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| Hooks not detected | Verify `~/.claude/settings.json` exists; reinstall if missing |
| JSON parse errors | Update to latest version with Python dict conversion |
| Connection failed | Check `curl -k https://your-endpoint:8443/api/health` |
| Wrong directory | Move `~/.claude-code/hooks/*` to `~/.claude/hooks/` |
### Debug Mode
Enable verbose debugging:
```bash
# Claude hooks debug
claude --debug hooks
# Individual hook testing
node ~/.claude/hooks/core/session-start.js
```
### Windows-Specific Considerations
- **Directory Structure**: Hooks install to `%USERPROFILE%\.claude\hooks\`
- **JSON Path Format**: Use backslashes or forward slashes
- **Python Executable**: Ensure Python is in PATH
## Performance Characteristics
The service is optimized for low-latency operations:
| Operation | First Call | Subsequent Calls |
|-----------|------------|-------------------|
| Search | ~50ms | ~5-10ms |
| Store | ~50ms | ~5-10ms |
| Health Check | ~5ms | ~1ms |
| Metric | Value |
|--------|-------|
| Memory Overhead | <10MB |
| Cost per 10-user deployment | ~$16.43/year |
资料来源：[src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)
## Next Steps
After completing this quick start guide, consider exploring:
- **API Reference**: Full endpoint documentation at `/api/docs`
- **Maintenance Scripts**: Database cleanup and type consolidation tools in `scripts/maintenance/`
- **Advanced Configuration**: Backend switching and hybrid deployment options
- **Claude Hooks Customization**: Fine-tune auto-capture behavior and verbosity levels
---
## System Architecture
### 相关页面
相关主题：[Storage Backends](#storage-backends), [Knowledge Graph and Entity Extraction](#knowledge-graph), [Memory Consolidation Engine](#consolidation-engine)
Related Source Files
以下源码文件用于生成本页说明：
- [src/mcp_memory_service/mcp_server.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py)
- [src/mcp_memory_service/server_impl.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.py)
- [src/mcp_memory_service/services/memory_service.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/memory_service.py)
- [src/mcp_memory_service/services/graph_service.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/graph_service.py)
- [src/mcp_memory_service/storage/factory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)
- [docs/architecture.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/architecture.md)
# System Architecture
## Overview
The MCP Memory Service is a semantic memory service built on the Model Context Protocol (MCP). It provides storage, retrieval, and search capabilities for AI-assisted workflows by maintaining a persistent vector-based memory store with automatic embedding generation.
**资料来源：[src/mcp_memory_service/api/__init__.py:1-20](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**
The architecture follows a layered design pattern with clear separation between the MCP protocol layer, business logic services, and storage abstraction layer.
## High-Level Architecture
```mermaid
graph TD
subgraph "Client Layer"
Claude[Claude Code]
CLI[CLI Client]
HTTP[HTTP Client]
MCP[MCP Client]
end
subgraph "Interface Layer"
FastAPI[FastAPI Server]
MCP_Server[MCP Server]
CLI_Interface[CLI Interface]
end
subgraph "Service Layer"
Memory_Service[Memory Service]
Graph_Service[Graph Service]
Response_Limiter[Response Limiter]
end
subgraph "Storage Layer"
Factory[Storage Factory]
SQLiteVec[sqlite_vec]
Litestream[Litestream Sync]
end
Client_Layer --> Interface_Layer
Claude --> MCP_Server
CLI --> CLI_Interface
HTTP --> FastAPI
Interface_Layer --> Service_Layer
Memory_Service --> Factory
Graph_Service --> Factory
Factory --> SQLiteVec
SQLiteVec --> Litestream
```
## Core Components
### MCP Server
The MCP Server (`mcp_server.py`) implements the Model Context Protocol, allowing AI assistants like Claude Code to interact with the memory service directly through standardized MCP tools.
**Key responsibilities:**
- Expose MCP tools for memory operations
- Handle tool invocation requests from MCP clients
- Coordinate with the Memory Service for all operations
**资料来源：[src/mcp_memory_service/mcp_server.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py)**
### Server Implementation
The `server_impl.py` serves as the primary server implementation, providing the HTTP/REST interface alongside MCP support.
**资料来源：[src/mcp_memory_service/server_impl.py:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.py)**
### Memory Service
The Memory Service (`memory_service.py`) is the core business logic layer that handles:
| Operation | Description |
|-----------|-------------|
| `store()` | Store new memories with automatic embedding generation |
| `search()` | Semantic similarity search using vector embeddings |
| `recall()` | Time-based memory retrieval with natural language expressions |
| `delete()` | Remove memories and their associated embeddings |
| `list_memories()` | Paginated listing of all memories |
**资料来源：[src/mcp_memory_service/services/memory_service.py:1-60](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/memory_service.py)**
### Graph Service
The Graph Service (`graph_service.py`) manages relationship tracking between memories, enabling complex queries about memory connections and dependencies.
**资料来源：[src/mcp_memory_service/services/graph_service.py:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/graph_service.py)**
## Storage Architecture
### Storage Factory Pattern
The storage layer uses a factory pattern (`storage/factory.py`) to abstract the underlying database implementation:
```mermaid
graph LR
Factory[Storage Factory] -->|Creates| SQLiteVec_Storage[SQLite Vec Storage]
Factory -->|Creates| InMemory_Storage[In-Memory Storage]
SQLiteVec_Storage -->|Uses| SQLite[(SQLite with vec extension)]
InMemory_Storage -->|Uses| RAM[(In-Memory)]
```
**资料来源：[src/mcp_memory_service/storage/factory.py:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)**
### SQLite Vec Backend
The default storage backend uses `sqlite_vec`, which provides:
- **Vector storage**: Native support for embedding storage and similarity search
- **SQLite reliability**: ACID transactions, proven durability
- **Low overhead**: <10MB memory footprint
- **Performance**: ~5-10ms subsequent calls after first call initialization
**资料来源：[src/mcp_memory_service/api/__init__.py:15-18](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**
### Litestream Synchronization
For production deployments, Litestream provides continuous database replication:
**资料来源：[src/mcp_memory_service/sync/litestream_config.py:1-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/sync/litestream_config.py)**
| Platform | Installation Command |
|----------|---------------------|
| macOS | `brew install benbjohnson/litestream/litestream` |
| Linux | `curl -LsS https://... \| tar -xzf -` |
| Windows | Manual download from GitHub releases |
## API Architecture
### REST API Endpoints
**资料来源：[src/mcp_memory_service/web/app.py:30-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)**
#### Memory Management
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/memories` | Store a new memory with automatic embedding generation |
| GET | `/api/memories` | List all memories with pagination support |
| GET | `/api/memories/{hash}` | Retrieve a specific memory by content hash |
| DELETE | `/api/memories/{hash}` | Delete a memory and its embeddings |
#### Search Operations
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/search` | Semantic similarity search using embeddings |
| GET | `/api/search/similar/{hash}` | Find memories similar to a specific one |
#### Real-time Events
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/events` | Subscribe to real-time memory events stream (SSE) |
| GET | `/api/events/stats` | View SSE connection statistics |
### Python API
The Python API provides programmatic access with low token overhead:
```python
from mcp_memory_service.api import search, store, health
# Search memories (~20 tokens)
results = search("architecture decisions", limit=5)
# Store memory (~15 tokens)
hash = store("New memory", tags=["note", "important"])
# Health check (~5 tokens)
info = health()
```
**资料来源：[src/mcp_memory_service/api/__init__.py:20-40](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**
## Response Management
### Response Limiter
The `response_limiter.py` module prevents context window overflow by truncating responses at memory boundaries.
**资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)**
```mermaid
graph TD
Request[Large Memory Request] --> Check{Under limit?}
Check -->|Yes| Return_Full[Return all memories]
Check -->|No| Truncate[Truncate at boundary]
Truncate --> Add_Header[Add truncation header]
Add_Header --> Return_Partial[Return partial results]
```
### Configuration
| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `MCP_MAX_RESPONSE_CHARS` | `0` (unlimited) | Maximum characters in responses |
## CLI Architecture
**资料来源：[src/mcp_memory_service/cli/main.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/cli/main.py)**
The CLI provides command-line access to all memory operations:
```bash
memory server # Start HTTP server
memory health # Check service health
memory logs --lines 30 # Show recent log entries
```
Compatibility entry points:
- `memory-server` (deprecated, redirects to `memory server`)
## Integration Points
### Claude Code Hooks
The system integrates with Claude Code through hooks that provide:
- Automatic memory loading on session start
- Context injection of relevant memories
- Session insight storage on session end
**资料来源：[claude-hooks/README.md:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)**
### Claude Commands
Custom slash commands for memory operations:
| Command | Purpose |
|---------|---------|
| `/memory-save` | Save current conversation as memory |
| `/memory-recall` | Time-based memory retrieval |
| `/memory-search` | Tag and content search |
| `/memory-context` | Session context integration |
| `/memory-health` | Service health check |
**资料来源：[claude_commands/README.md:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)**
## Data Flow
```mermaid
sequenceDiagram
participant Client
participant API
participant MemoryService
participant Storage
participant Litestream
Client->>API: Store memory request
API->>MemoryService: Save operation
MemoryService->>MemoryService: Generate embedding
MemoryService->>Storage: Store content + vector
Storage->>Litestream: Replicate to S3/GCS
Storage-->>MemoryService: Confirmation
MemoryService-->>API: Success response
API-->>Client: Memory hash returned
Client->>API: Search request
API->>MemoryService: Query
MemoryService->>MemoryService: Generate query embedding
MemoryService->>Storage: Vector similarity search
Storage-->>MemoryService: Top K results
MemoryService-->>API: Ranked results
API-->>Client: Search results
```
## Maintenance Operations
### Memory Type Consolidation
The system supports consolidating fragmented memory types into a standardized taxonomy:
**资料来源：[scripts/maintenance/README.md:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)**
**Standard 24-Type Taxonomy:**
- Content Types: `note`, `reference`, `document`, `guide`
- Activity Types: `session`, `implementation`, `analysis`
### Sync Export/Import
**资料来源：[scripts/sync/README.md:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)**
| Operation | Performance |
|-----------|-------------|
| Export | ~1000 memories/second |
| Import | ~500 memories/second with deduplication |
| File Size | ~1KB per memory |
## Performance Characteristics
| Metric | Value |
|--------|-------|
| First call latency | ~50ms (includes storage initialization) |
| Subsequent calls | ~5-10ms (connection reused) |
| Memory overhead | <10MB |
| Annual cost | ~$16.43/year per 10-user deployment (at $0.15/1M tokens) |
**资料来源：[src/mcp_memory_service/api/__init__.py:12-15](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**
## Architecture Summary
The MCP Memory Service architecture is designed around three principles:
1. **Separation of Concerns**: Clear boundaries between protocol handling, business logic, and storage
2. **Multiple Interfaces**: Support for MCP, REST, Python API, and CLI access patterns
3. **Production Ready**: Built-in replication, response limiting, and maintenance tools
---
## Storage Backends
### 相关页面
相关主题：[System Architecture](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mcp_memory_service/storage/sqlite_vec.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/sqlite_vec.py)
- [src/mcp_memory_service/storage/cloudflare.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/cloudflare.py)
- [src/mcp_memory_service/storage/milvus.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/milvus.py)
- [src/mcp_memory_service/storage/hybrid.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/hybrid.py)
- [docs/guides/STORAGE_BACKENDS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/STORAGE_BACKENDS.md)
- [docs/milvus-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/milvus-backend.md)
- [docs/sqlite-vec-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/sqlite-vec-backend.md)
# Storage Backends
The mcp-memory-service project implements a **pluggable storage backend architecture** that enables users to choose between different vector database technologies for storing and searching semantic memories. This abstraction layer decouples the core memory service logic from specific database implementations, providing flexibility in deployment scenarios.
## Architecture Overview
The storage system follows a factory pattern with a unified interface. All storage implementations inherit from a common base class that defines the contract for memory operations: store, retrieve, search, and delete.
```mermaid
graph TD
A[Memory Service] --> B[Storage Factory]
B --> C[sqlite_vec Storage]
B --> D[Cloudflare Storage]
B --> E[Milvus Storage]
B --> F[Hybrid Storage]
C --> G[(Local SQLite DB)]
D --> H[(Cloudflare D1 + Vectorize)]
E --> I[(Milvus Collection)]
F --> J[(Cloudflare + SQLite)]
```
资料来源：[src/mcp_memory_service/storage/factory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)
## Supported Storage Backends
| Backend | Description | Best For |
|---------|-------------|----------|
| `sqlite_vec` | Local SQLite database with vec0 extension | Single-user, offline-first, privacy-focused |
| `cloudflare` | Cloudflare D1 database + Vectorize API | Cloud-native, multi-device sync |
| `milvus` | Milvus vector database | Enterprise-scale, high-performance |
| `hybrid` | Cloudflare + SQLite combination | Multi-device with local backup |
资料来源：[docs/guides/STORAGE_BACKENDS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/STORAGE_BACKENDS.md)
## Core Interface
All storage backends implement a common interface defined through the base storage class. The interface includes:
### Storage Methods
| Method | Purpose | Parameters |
|--------|---------|------------|
| `store(memory)` | Store a new memory with embedding | Memory object with content, tags, metadata |
| `retrieve(hash)` | Retrieve memory by content hash | content_hash: str |
| `search(query, limit)` | Semantic search using embeddings | query: str, limit: int |
| `search_by_tag(tags, match_all)` | Tag-based filtering | tags: list, match_all: bool |
| `list_memories(page, page_size)` | Paginated memory listing | page: int, page_size: int |
| `delete(hash)` | Remove memory and embeddings | content_hash: str |
资料来源：[src/mcp_memory_service/api/operations.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)
## SQLite Vec Backend
The `sqlite_vec` backend is the default and most widely-used storage option. It leverages the `sqlite-vec` extension to enable vector similarity search directly within SQLite.
### Configuration
| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `SQLITE_VEC_DB_PATH` | `~/.local/share/mcp-memory/sqlite_vec.db` | Path to SQLite database file |
| `EMBEDDING_MODEL_NAME` | `sentence-transformers/all-MiniLM-L6-v2` | Embedding model for vectorization |
### Database Schema
The SQLite backend stores memories in a relational table with the following structure:
```sql
CREATE TABLE memories (
content TEXT NOT NULL,
content_hash TEXT PRIMARY KEY,
tags TEXT,
memory_type TEXT,
metadata TEXT,
created_at REAL,
updated_at REAL,
created_at_iso TEXT,
updated_at_iso TEXT
);
CREATE VIRTUAL TABLE memories_embeddings USING vec0(
content_hash TEXT PRIMARY KEY,
embedding FLOAT[384]
);
```
资料来源：[docs/sqlite-vec-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/sqlite-vec-backend.md)
### Performance Characteristics
| Metric | Value |
|--------|-------|
| Search latency | 5-10ms |
| Store latency | 10-20ms (includes embedding) |
| Memory overhead | <10MB |
| Capacity | Limited by disk space |
## Cloudflare Backend
The Cloudflare backend provides cloud-native storage using Cloudflare's D1 (SQLite-compatible) database and Vectorize (vector search) API.
### Configuration
| Environment Variable | Required | Description |
|---------------------|----------|-------------|
| `CLOUDFLARE_API_TOKEN` | Yes | Cloudflare API authentication token |
| `CLOUDFLARE_ACCOUNT_ID` | Yes | Cloudflare account identifier |
| `CLOUDFLARE_VECTORIZE_INDEX` | Yes | Vectorize index name |
| `CLOUDFLARE_D1_DATABASE_ID` | Yes | D1 database identifier |
| `CLOUDFLARE_R2_BUCKET` | No | R2 bucket for large content storage |
| `CLOUDFLARE_EMBEDDING_MODEL` | No | Embedding model override |
| `CLOUDFLARE_LARGE_CONTENT_THRESHOLD` | No | Size threshold for R2 storage |
| `CLOUDFLARE_MAX_RETRIES` | No | Retry attempts for API calls |
| `CLOUDFLARE_BASE_DELAY` | No | Initial retry delay in seconds |
### Initialization
```python
storage = CloudflareStorage(
api_token=CLOUDFLARE_API_TOKEN,
account_id=CLOUDFLARE_ACCOUNT_ID,
vectorize_index=CLOUDFLARE_VECTORIZE_INDEX,
d1_database_id=CLOUDFLARE_D1_DATABASE_ID,
r2_bucket=CLOUDFLARE_R2_BUCKET,
embedding_model=CLOUDFLARE_EMBEDDING_MODEL,
large_content_threshold=CLOUDFLARE_LARGE_CONTENT_THRESHOLD,
max_retries=CLOUDFLARE_MAX_RETRIES,
base_delay=CLOUDFLARE_BASE_DELAY
)
```
资料来源：[src/mcp_memory_service/storage/factory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)
## Milvus Backend
The Milvus backend targets enterprise deployments requiring high-performance, distributed vector search capabilities.
### Configuration
| Environment Variable | Required | Description |
|---------------------|----------|-------------|
| `MILVUS_URI` | Yes | Milvus server URI |
| `MILVUS_TOKEN` | No | Authentication token |
| `MILVUS_COLLECTION_NAME` | No | Collection name (default: `memories`) |
| `EMBEDDING_MODEL_NAME` | No | Embedding model |
### Initialization
```python
storage = MilvusMemoryStorage(
uri=MILVUS_URI,
token=MILVUS_TOKEN,
collection_name=MILVUS_COLLECTION_NAME,
embedding_model=EMBEDDING_MODEL_NAME,
)
```
资料来源：[docs/milvus-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/milvus-backend.md)
## Hybrid Backend
The hybrid backend combines Cloudflare storage with local SQLite-vec backup, enabling multi-device synchronization while maintaining offline capability.
### Architecture
```mermaid
graph LR
A[Local SQLite DB] <--> B[Hybrid Storage]
B <--> C[Cloudflare D1]
B <--> D[Cloudflare Vectorize]
E[Write Operations] --> B
F[Read Operations] --> B
```
### Configuration
The hybrid backend requires both Cloudflare and SQLite configuration:
```python
cloudflare_config = {
'api_token': CLOUDFLARE_API_TOKEN,
'account_id': CLOUDFLARE_ACCOUNT_ID,
'vectorize_index': CLOUDFLARE_VECTORIZE_INDEX,
'd1_database_id': CLOUDFLARE_D1_DATABASE_ID,
}
storage = HybridMemoryStorage(
cloudflare_config=cloudflare_config,
local_db_path=LOCAL_DB_PATH,
)
```
## Storage Factory
The `get_storage()` function in the factory module handles backend instantiation based on configuration:
```python
async def get_storage(backend: Optional[str] = None) -> BaseStorage:
"""Get storage instance based on configured or specified backend."""
backend = backend or os.getenv("MCP_MEMORY_STORAGE_BACKEND", "sqlite_vec")
if backend == "cloudflare":
return CloudflareStorage(...)
elif backend == "milvus":
return MilvusMemoryStorage(...)
elif backend == "hybrid":
return HybridMemoryStorage(...)
else:
return SQLiteVecStorage(...)
```
资料来源：[src/mcp_memory_service/storage/factory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)
## HTTP Client Backend
For distributed deployments, the project supports HTTP-based storage access through an `HttpStorage` client. This enables communication with remote MCP Memory Service instances.
### HTTP API Endpoints
| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/api/memories` | Store a new memory |
| GET | `/api/memories` | List memories with pagination |
| GET | `/api/memories/{hash}` | Retrieve specific memory |
| DELETE | `/api/memories/{hash}` | Delete memory |
| POST | `/api/search` | Semantic search |
| GET | `/api/search/similar/{hash}` | Find similar memories |
| GET | `/api/events` | SSE event stream |
### Time Filter Format
When searching by time ranges, the HTTP client converts Unix timestamps to ISO date format:
```python
def _build_time_filter(time_start: Optional[float], time_end: Optional[float]) -> Optional[str]:
if time_start and time_end:
return f"between {_to_date(time_start)} and {_to_date(time_end)}"
elif time_start:
return _to_date(time_start)
return _to_date(time_end)
```
资料来源：[src/mcp_memory_service/storage/http_client.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/http_client.py)
## Backend Selection
### Decision Matrix
| Use Case | Recommended Backend |
|----------|---------------------|
| Single machine, privacy-sensitive | `sqlite_vec` |
| Multi-device with cloud sync | `cloudflare` |
| Enterprise with high volume | `milvus` |
| Local backup + cloud sync | `hybrid` |
### Selecting Backend via CLI
When using the CLI for operations:
```bash
# Use SQLite backend (default)
memory ingest-document doc.pdf
# Use Cloudflare backend
memory ingest-document doc.pdf --storage-backend cloudflare
# Use hybrid backend
memory ingest-document doc.pdf --storage-backend hybrid
```
## Maintenance Operations
### Embedding Migration
To migrate to a different embedding model (handles dimension changes):
```bash
python scripts/maintenance/migrate_embeddings.py --url http://localhost:8000 --model new-model --dry-run
```
### Database Repair Scripts
| Script | Purpose |
|--------|---------|
| `repair_memories.py` | Repair corrupted memory entries |
| `repair_sqlite_vec_embeddings.py` | Fix embedding inconsistencies |
| `repair_zero_embeddings.py` | Fix zero/null embeddings |
| `cleanup_corrupted_encoding.py` | Fix corrupted emoji encoding |
### Backup Strategy
For `sqlite_vec` backend, Litestream provides continuous replication:
```bash
# Configure in litestream.yml
dbs:
- path: ~/.local/share/mcp-memory/sqlite_vec.db
replicas:
- url: s3://your-bucket/mcp-memory/
```
资料来源：[scripts/sync/litestream/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/litestream/README.md)
## Response Limiting
All storage backends support response size limiting through the `ResponseLimiter` utility to prevent oversized responses:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `max_chars` | 10000 | Maximum characters in response |
| `max_results` | 50 | Maximum memories to return |
The limiter calculates estimated memory sizes including overhead and truncates at memory boundaries to ensure consistent response sizes.
资料来源：[src/mcp_memory_service/server/utils/response_limiter.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)
---
## Knowledge Graph and Entity Extraction
### 相关页面
相关主题：[System Architecture](#architecture), [Memory Consolidation Engine](#consolidation-engine), [Quality Scoring System](#quality-scoring)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mcp_memory_service/models/association.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/association.py)
- [src/mcp_memory_service/reasoning/entities.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/entities.py)
- [src/mcp_memory_service/reasoning/inference.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/inference.py)
- [src/mcp_memory_service/storage/graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.py)
- [src/mcp_memory_service/storage/milvus_graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/milvus_graph.py)
- [src/mcp_memory_service/server/handlers/graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)
- [src/mcp_memory_service/consolidation/consolidator.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)
# Knowledge Graph and Entity Extraction
## Overview
The MCP Memory Service includes a sophisticated Knowledge Graph system that enables semantic relationships between memories, automatic entity extraction, and intelligent relationship inference. This feature transforms isolated memory entries into an interconnected knowledge network that supports advanced queries like graph traversal, entity-based retrieval, and similarity analysis.
The knowledge graph layer sits above the core memory storage, providing:
- **Entity Extraction**: Automatic identification of people, organizations, locations, and concepts from memory content
- **Relationship Mapping**: Discovery and storage of connections between memories based on semantic similarity and content analysis
- **Graph Traversal**: Navigation of memory relationships using configurable depth and radius parameters
- **Association Memory**: Automatic creation of memory entries that document discovered relationships between existing memories
- **Relationship Inference**: AI-powered inference of relationship types (causes, fixes, contradicts, supports, follows)
## Architecture
```mermaid
graph TD
subgraph "Memory Layer"
M1[Memory 1]
M2[Memory 2]
M3[Memory 3]
end
subgraph "Entity Extraction"
EE[EntityExtractor]
NER[NER Processing]
PAT[Pattern Matching]
end
subgraph "Graph Storage"
GS[GraphStorage]
RI[RelationshipInference]
AM[AssociationMemory]
end
subgraph "Query Interfaces"
GT[Graph Tools]
ST[Search Tools]
end
M1 --> EE
M2 --> EE
M3 --> EE
EE --> NER
EE --> PAT
NER --> GS
PAT --> GS
GS --> RI
RI --> AM
AM --> GS
GT --> GS
ST --> GS
```
### Core Components
| Component | File | Purpose |
|-----------|------|---------|
| `EntityExtractor` | `src/mcp_memory_service/reasoning/entities.py` | Extracts entities from memory content |
| `RelationshipInferenceEngine` | `src/mcp_memory_service/reasoning/inference.py` | Infers relationship types between memories |
| `GraphStorage` | `src/mcp_memory_service/storage/graph.py` | SQLite-based graph storage backend |
| `MilvusGraphStorage` | `src/mcp_memory_service/storage/milvus_graph.py` | Milvus vector database backend |
| `MemoryConsolidator` | `src/mcp_memory_service/consolidation/consolidator.py` | Creates and manages association memories |
| `Association` | `src/mcp_memory_service/models/association.py` | Data model for memory associations |
资料来源：[src/mcp_memory_service/reasoning/entities.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/entities.py)
## Entity Extraction
### Overview
Entity extraction automatically identifies and categorizes entities within memory content. The system supports multiple entity types and uses both pattern-based and NER (Named Entity Recognition) approaches.
资料来源：[src/mcp_memory_service/reasoning/entities.py:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/entities.py)
### Supported Entity Types
The system recognizes the following entity categories:
| Entity Type | Description | Examples |
|-------------|-------------|----------|
| `person` | Human individuals | "John", "Alice Chen" |
| `organization` | Companies, teams, agencies | "Acme Corp", "Engineering Team" |
| `location` | Physical places | "San Francisco", "Building A" |
| `concept` | Abstract ideas and concepts | "machine learning", "agile methodology" |
| `technology` | Tools, frameworks, languages | "Python", "React", "Docker" |
| `date` | Temporal references | "December 2024", "Q1" |
| `project` | Named projects or initiatives | "Project Alpha", "Apollo Initiative" |
### Extraction Process
```mermaid
graph LR
A[Memory Content] --> B[Pattern Matching]
A --> C[NER Processing]
B --> D[Entity Deduplication]
C --> D
D --> E[Entity Metadata]
E --> F[Store Entity Links]
```
The extraction process follows these steps:
1. **Pattern Matching**: Initial scan for known patterns (email, URL, date formats, capitalization patterns)
2. **NER Processing**: Language model-based entity recognition for contextual entity types
3. **Entity Deduplication**: Normalization and merging of duplicate entities
4. **Metadata Generation**: Creation of entity metadata including confidence scores
5. **Storage**: Persisting entity links to the graph storage
### MCP Tool Interface
Entities can be extracted and stored via the MCP `memory_graph` tool:
资料来源：[src/mcp_memory_service/server/handlers/graph.py:50-75](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)
```json
{
"action": "extract_entities",
"hash": "abc123def456"
}
```
**Response Example:**
```json
{
"hash": "abc123def456",
"entities_extracted": 5,
"entities": [
{"name": "Python", "type": "technology", "confidence": 0.95},
{"name": "FastAPI", "type": "technology", "confidence": 0.92}
]
}
```
## Knowledge Graph Storage
### Storage Backends
The knowledge graph supports multiple storage backends:
| Backend | File | Use Case |
|---------|------|----------|
| SQLite Graph | `src/mcp_memory_service/storage/graph.py` | Default, single-node deployments |
| Milvus Graph | `src/mcp_memory_service/storage/milvus_graph.py` | Large-scale, distributed deployments |
资料来源：[src/mcp_memory_service/storage/graph.py:1-100](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.py)
### Graph Data Model
The graph storage maintains the following data structures:
#### Entities Table
Stores extracted entities linked to memories:
| Field | Type | Description |
|-------|------|-------------|
| `entity_id` | TEXT | Unique entity identifier |
| `name` | TEXT | Entity name |
| `entity_type` | TEXT | Entity category |
| `memory_hash` | TEXT | Associated memory hash |
| `confidence` | REAL | Extraction confidence score |
#### Relationships Table
Stores relationships between memories:
| Field | Type | Description |
|-------|------|-------------|
| `relationship_id` | TEXT | Unique relationship identifier |
| `source_hash` | TEXT | Source memory hash |
| `target_hash` | TEXT | Target memory hash |
| `relationship_type` | TEXT | Type (similar, causes, fixes, etc.) |
| `similarity_score` | REAL | Calculated similarity (0.0-1.0) |
| `metadata` | JSON | Additional relationship metadata |
资料来源：[src/mcp_memory_service/models/association.py:1-60](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/association.py)
### Graph Operations
#### Store Entity Link
```python
async def store_entity_link(
memory_hash: str,
entity_name: str,
entity_type: str
) -> bool:
```
Links an extracted entity to a memory for future retrieval and graph queries.
资料来源：[src/mcp_memory_service/storage/graph.py:150-180](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.py)
#### Get Memory Subgraph
Retrieves a local subgraph centered on a specific memory:
```python
async def get_memory_subgraph(
memory_hash: str,
radius: int = 2
) -> Dict[str, Any]:
```
Parameters:
- `memory_hash`: Center memory for subgraph traversal
- `radius`: Maximum traversal depth (default: 2)
#### Graph Traversal
```python
async def traverse_graph(
hash1: str,
hash2: str,
max_depth: int = 5
) -> List[Dict[str, Any]]:
```
Finds paths between two memories up to a specified depth.
资料来源：[src/mcp_memory_service/server/handlers/graph.py:20-45](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)
## Relationship Inference
### RelationshipInferenceEngine
The relationship inference engine analyzes memory content pairs to determine semantic relationships:
资料来源：[src/mcp_memory_service/reasoning/inference.py:1-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/inference.py)
### Supported Relationship Types
| Type | Description | Example |
|------|-------------|---------|
| `causes` | Source leads to target | "Changed config" → "System crashed" |
| `fixes` | Source resolves target | "Applied patch" → "Bug #123" |
| `contradicts` | Sources conflict | "Use X" vs "Don't use X" |
| `supports` | Source validates target | "Test results" → "Implementation works" |
| `follows` | Temporal sequence | "Phase 1 complete" → "Phase 2 started" |
| `related` | General connection | Topic similarity without specific type |
### Inference Process
```mermaid
graph TD
M1[Memory 1] --> C1[Content Analysis]
M2[Memory 2] --> C2[Content Analysis]
C1 --> SIM[Similarity Check]
C2 --> SIM
SIM --> RT{Relationship Type?}
RT -->|High Similarity| SA[Same Aspect]
RT -->|Causal Keywords| CA[Causal Link]
RT -->|Action Keywords| AC[Action Link]
RT -->|Negation| CN[Contradiction]
SA --> ST[Store Relationship]
CA --> ST
AC --> ST
CN --> ST
```
## Association Memory
### Overview
Association memories are automatically generated entries that document discovered relationships between existing memories. They provide a memory-level representation of graph connections, enabling search and retrieval of relationship information.
资料来源：[src/mcp_memory_service/consolidation/consolidator.py:150-200](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)
### Association Data Model
```python
class Association:
source_memory_hashes: List[str]
similarity_score: float
connection_type: str
discovery_method: str
discovery_date: datetime
metadata: Dict[str, Any]
```
### Association Memory Structure
When an association is stored as a memory:
```python
association_memory = Memory(
content=f"Connected {source_hashes[0][:8]} and {source_hashes[1][:8]} by {connection_type}",
content_hash=f"assoc_{source_hashes[0][:8]}_{source_hashes[1][:8]}",
tags=["association", "discovered", connection_type],
memory_type="observation",
metadata={
"source_memory_hashes": source_hashes,
"similarity_score": similarity,
"connection_type": connection_type,
"discovery_method": association.discovery_method,
"discovery_date": association.discovery_date.isoformat(),
}
)
```
资料来源：[src/mcp_memory_service/consolidation/consolidator.py:170-195](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)
### Storage Process
```mermaid
graph LR
A[Memory Pair] --> B[Similarity Analysis]
B --> C{Score >= Threshold?}
C -->|Yes| D[Type Classification]
C -->|No| E[Skip]
D --> F[Create Association]
F --> G[Store Association Memory]
G --> H[Update Graph]
```
The consolidator stores association memories with `skip_semantic_dedup=True` to prevent deduplication conflicts with templated content.
资料来源：[src/mcp_memory_service/consolidation/consolidator.py:195-210](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)
## MCP Tools Reference
### memory_graph
Main tool for graph operations:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | Yes | Operation: `traverse`, `subgraph`, `extract_entities` |
| `hash` | string | Conditional | Memory hash for subgraph/entities actions |
| `hash1` | string | Conditional | Source hash for traversal |
| `hash2` | string | Conditional | Target hash for traversal |
| `radius` | integer | No | Subgraph radius (default: 2) |
| `max_depth` | integer | No | Traversal max depth (default: 5) |
#### Action Examples
**Extract Entities:**
```json
{
"action": "extract_entities",
"hash": "memory_hash_here"
}
```
**Get Subgraph:**
```json
{
"action": "subgraph",
"hash": "memory_hash_here",
"radius": 3
}
```
**Traverse Graph:**
```json
{
"action": "traverse",
"hash1": "memory_hash_1",
"hash2": "memory_hash_2",
"max_depth": 5
}
```
资料来源：[src/mcp_memory_service/server/handlers/graph.py:1-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)
## Maintenance Scripts
### update_graph_relationship_types.py
Located in `scripts/maintenance/`, this script infers relationship types for existing graph associations:
```bash
# Dry run (preview changes)
python scripts/maintenance/update_graph_relationship_types.py --dry-run
# Execute inference
python scripts/maintenance/update_graph_relationship_types.py
```
**Features:**
- Uses `RelationshipInferenceEngine` for type inference
- Supports dry-run mode for safety
- Automatic backup before execution
- Updates relationship metadata in graph storage
资料来源：[scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)
## Configuration
### Graph Storage Configuration
The graph storage is automatically initialized when the storage service starts. No explicit configuration is required for SQLite-based storage.
For Milvus-based storage, configure the following environment variables:
| Variable | Description | Default |
|----------|-------------|---------|
| `MILVUS_HOST` | Milvus server host | localhost |
| `MILVUS_PORT` | Milvus server port | 19530 |
| `MILVUS_COLLECTION` | Collection name | memory_graph |
### Entity Extraction Configuration
Entity extraction settings can be configured in the service configuration:
| Setting | Type | Description |
|---------|------|-------------|
| `entity_types` | List[str] | Enabled entity types |
| `min_confidence` | float | Minimum confidence threshold (0.0-1.0) |
| `enable_ner` | bool | Enable NER processing |
| `pattern_weight` | float | Weight for pattern matching |
## Error Handling
The graph operations return standardized error responses:
```json
{
"error": "Error message describing the issue"
}
```
Common error scenarios:
- Memory not found for entity extraction
- Graph storage not initialized
- Invalid hash format
- Maximum depth exceeded during traversal
资料来源：[src/mcp_memory_service/server/handlers/graph.py:55-65](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)
## Best Practices
1. **Entity Naming**: Use consistent entity naming conventions for better graph queries
2. **Memory Organization**: Group related content in the same memory to strengthen association discovery
3. **Regular Maintenance**: Run `update_graph_relationship_types.py` periodically to classify new associations
4. **Tag Usage**: Tag memories with semantic tags to improve entity and relationship extraction
5. **Graph Traversal**: Use appropriate radius/depth limits to prevent performance issues with highly connected memories
## See Also
- [Memory Storage](storage-overview.md) - Core memory storage architecture
- [Consolidation System](consolidation.md) - Association memory generation
- [Reasoning Engine](reasoning.md) - Entity extraction and inference details
- [Maintenance Scripts](../scripts/maintenance/README.md) - Graph maintenance utilities
---
## Memory Consolidation Engine
### 相关页面
相关主题：[Knowledge Graph and Entity Extraction](#knowledge-graph), [Quality Scoring System](#quality-scoring), [System Architecture](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mcp_memory_service/consolidation/consolidator.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)
- [src/mcp_memory_service/consolidation/scheduler.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/scheduler.py)
- [src/mcp_memory_service/consolidation/decay.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/decay.py)
- [src/mcp_memory_service/consolidation/forgetting.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/forgetting.py)
- [src/mcp_memory_service/consolidation/insights.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/insights.py)
- [docs/guides/memory-consolidation-guide.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/memory-consolidation-guide.md)
# Memory Consolidation Engine
The Memory Consolidation Engine is a core subsystem of the MCP Memory Service that manages the lifecycle of stored memories through intelligent compression, decay analysis, and selective forgetting mechanisms. It ensures the memory store remains efficient, relevant, and optimized for long-term semantic retrieval.
## Overview
As memories accumulate over time, the consolidation engine performs background operations to:
- **Compress redundant memories** into consolidated summaries
- **Apply decay algorithms** to age out less relevant information
- **Forget obsolete entries** based on configurable time horizons
- **Generate insights** from consolidated memory patterns
```mermaid
graph TD
A[New Memory] --> B[Memory Store]
B --> C{Consolidation Scheduler}
C --> D[Decay Analysis]
C --> E[Compression]
C --> F[Forgetting Check]
D --> G[Relevance Score Update]
E --> H[Consolidated Memory]
F --> I[Memory Deletion]
G --> H
H --> J[Insights Generation]
J --> K[Updated Memory Store]
```
## Architecture
The consolidation engine comprises five primary modules located in `src/mcp_memory_service/consolidation/`:
| Module | Purpose | Key Functions |
|--------|---------|---------------|
| `consolidator.py` | Core consolidation orchestration | Main consolidation loop, memory merging |
| `scheduler.py` | Automated scheduling of consolidation tasks | Daily, weekly, monthly job scheduling |
| `decay.py` | Relevance decay calculations | Age-based score reduction algorithms |
| `forgetting.py` | Selective memory removal | Time-horizon based forgetting policies |
| `insights.py` | Post-consolidation analysis | Pattern detection, summary generation |
资料来源：[src/mcp_memory_service/consolidation/scheduler.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/scheduler.py)
## Consolidation Time Horizons
The engine operates on three configurable time horizons that determine consolidation aggressiveness:
### Weekly Consolidation
- Processes recent memories (typically 7 days)
- Light compression to maintain detail
- Preserves high-relevance memories unchanged
### Monthly Consolidation
- Reviews memories from past 30 days
- Moderate compression and decay application
- Identifies patterns across recent sessions
### Quarterly Consolidation
- Full store analysis
- Aggressive forgetting of stale entries
- Major compression of redundant information
资料来源：[src/mcp_memory_service/api/operations.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)
## API Integration
### REST API Endpoint
```
POST /api/consolidate
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `time_horizon` | string | Yes | One of: `daily`, `weekly`, `monthly` |
**Example Request:**
```bash
curl -X POST https://localhost:8443/api/consolidate \
-H "Content-Type: application/json" \
-d '{"time_horizon": "weekly"}'
```
**Example Response:**
```json
{
"status": "completed",
"time_horizon": "weekly",
"memories_processed": 2418,
"compressed": 156,
"forgotten": 43
}
```
资料来源：[src/mcp_memory_service/api/operations.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)
### Python API
```python
from mcp_memory_service.api import consolidate
# Async consolidation
result = await consolidate('weekly')
print(f"Compressed: {result.compressed}, Forgotten: {result.forgotten}")
```
**Return Value Properties:**
| Property | Type | Description |
|----------|------|-------------|
| `status` | string | Completion status |
| `time_horizon` | string | Horizon used |
| `memories_processed` | int | Total memories reviewed |
| `compressed` | int | Number of memories consolidated |
| `forgotten` | int | Number of memories deleted |
## Scheduler Configuration
The consolidation scheduler runs automated tasks based on configured schedules:
```mermaid
graph LR
A[Scheduler Init] --> B{Job Queue}
B --> C[Daily Job
T+00:00]
B --> D[Weekly Job
Sunday T+02:00]
B --> E[Monthly Job
1st T+03:00]
```
**Scheduler Status Model:**
```python
CompactSchedulerStatus:
running: bool
next_daily: datetime | None
next_weekly: datetime | None
next_monthly: datetime | None
jobs_executed: int
jobs_failed: int
```
资料来源：[src/mcp_memory_service/consolidation/scheduler.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/scheduler.py)
## Decay Algorithm
The decay module applies relevance scoring based on memory age and access patterns:
```python
def calculate_decay_score(memory_age_days: int, access_frequency: float) -> float:
"""
Returns relevance score between 0.0 and 1.0
Lower scores indicate memories approaching forgetting threshold
"""
```
**Decay Factors:**
| Factor | Description | Weight |
|--------|-------------|--------|
| Time Since Creation | Older memories decay faster | 0.4 |
| Access Frequency | Frequently accessed memories decay slower | 0.3 |
| Tag Relevance | Tagged memories maintain higher scores | 0.2 |
| Memory Type | System vs user memory decay rates differ | 0.1 |
资料来源：[src/mcp_memory_service/consolidation/decay.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/decay.py)
## Forgetting Mechanism
The forgetting module determines which memories should be permanently removed:
```python
def should_forget(memory: Memory, horizon: str) -> bool:
"""
Evaluates if a memory meets forgetting criteria
Returns True if memory should be deleted
"""
```
**Forgetting Criteria by Horizon:**
| Horizon | Age Threshold | Min Decay Score | Additional Checks |
|---------|--------------|-----------------|-------------------|
| `daily` | 90 days | 0.1 | None |
| `weekly` | 180 days | 0.2 | Duplicate detection |
| `monthly` | 365 days | 0.3 | Pattern analysis |
**Safety Features:**
- Automatic backup before deletion
- Transaction-based deletion (atomic rollback on failure)
- Database lock detection to prevent concurrent access issues
- Disk space verification before execution
资料来源：[src/mcp_memory_service/consolidation/forgetting.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/forgetting.py)
## Performance Characteristics
| Metric | Value |
|--------|-------|
| Typical Duration | 10-30 seconds (varies with memory count) |
| Scaling | ~10ms per memory processed |
| Memory Overhead | <10MB during operation |
| Background Operation | Non-blocking in HTTP server context |
**Performance Tips:**
- Schedule consolidation during low-usage periods
- Large stores (>10,000 memories) may take longer
- Disable automatic scheduling for resource-constrained environments
## Insights Generation
After consolidation, the insights module analyzes patterns:
```python
def generate_insights(consolidated_memories: List[Memory]) -> List[Insight]:
"""
Produces actionable insights from consolidated memory patterns
"""
```
**Insight Types:**
| Type | Description |
|------|-------------|
| `pattern` | Recurring themes detected |
| `summary` | Condensed representation of grouped memories |
| `recommendation` | Suggestions based on memory patterns |
| `conflict` | Detected contradictions between memories |
资料来源：[src/mcp_memory_service/consolidation/insights.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/insights.py)
## Configuration
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_CONSOLIDATION_ENABLED` | `true` | Enable/disable automatic consolidation |
| `MCP_CONSOLIDATION_SCHEDULE` | `daily` | Default schedule |
| `MCP_MAX_RESPONSE_CHARS` | `0` | Response truncation (0 = unlimited) |
### Scheduler Settings
Configure in `~/.claude/hooks/config.json`:
```json
{
"consolidation": {
"schedule": {
"daily": "0 0 * * *",
"weekly": "0 2 * * 0",
"monthly": "0 3 1 * *"
},
"enabled": true,
"horizons": ["daily", "weekly"]
}
}
```
## Troubleshooting
### Common Issues
| Issue | Cause | Solution |
|-------|-------|----------|
| Consolidation fails silently | Database locked | Stop MCP clients before running |
| High memory usage during consolidation | Large store size | Increase `MCP_MAX_RESPONSE_CHARS` |
| Scheduler not running | Service not started | Check `systemctl --user status mcp-memory.service` |
### Verification
```bash
# Check scheduler status
curl https://localhost:8443/api/consolidate/status
# Manual consolidation (dry-run)
curl -X POST https://localhost:8443/api/consolidate \
-d '{"time_horizon": "weekly", "dry_run": true}'
```
## Further Reference
- [Memory Consolidation Guide](docs/guides/memory-consolidation-guide.md) - Detailed usage documentation
- [API Reference](src/mcp_memory_service/api/operations.py) - Full API specification
- [CLI Commands](claude_commands/README.md) - Command-line consolidation tools
---
## Quality Scoring System
### 相关页面
相关主题：[Memory Consolidation Engine](#consolidation-engine), [System Architecture](#architecture), [Quick Start Guide](#quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mcp_memory_service/quality/\_\_init\_\_.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/__init__.py)
- [src/mcp_memory_service/quality/onnx_ranker.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/onnx_ranker.py)
- [src/mcp_memory_service/quality/scorer.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/scorer.py)
- [src/mcp_memory_service/quality/ai_evaluator.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/ai_evaluator.py)
- [src/mcp_memory_service/quality/implicit_signals.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/implicit_signals.py)
- [src/mcp_memory_service/quality/config.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/config.py)
- [src/mcp_memory_service/server/handlers/quality.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/quality.py)
# Quality Scoring System
The Quality Scoring System is a multi-layered evaluation framework within the MCP Memory Service that assesses, ranks, and maintains memory content quality. It provides both automatic quality assessment through machine learning models and explicit user feedback mechanisms to ensure that memories retain high-value information over time.
## Overview
The system addresses a fundamental challenge in semantic memory systems: not all stored memories have equal importance or relevance. Over time, memory stores can become cluttered with transient information, low-value summaries, and outdated content that degrades the overall utility of the memory service.
The Quality Scoring System solves this by implementing:
- **Automatic Quality Assessment**: Uses ONNX-based ML models to evaluate content quality without manual intervention
- **Implicit Signal Detection**: Analyzes behavioral patterns to infer memory importance
- **Manual Rating Support**: Allows users to explicitly rate memory quality
- **Quality-Aware Search**: Boosts high-quality memories in search results
- **Maintenance Operations**: Provides tools for quality-based memory management
## Architecture
The Quality Scoring System follows a modular architecture with four primary components that work together to provide comprehensive quality evaluation.
```mermaid
graph TD
A[Memory Content] --> B[QualityScorer]
B --> C[ONNXRankerModel]
B --> D[QualityEvaluator]
B --> E[ImplicitSignalsEvaluator]
C --> F[CompactSearchResult]
D --> F
E --> F
G[User Rating] --> H[handle_rate_memory]
H --> B
I[Search Query] --> J[quality_boost Parameter]
J --> F
K[Maintenance Operations] --> L[handle_maintain]
L --> B
```
## Core Components
### QualityConfig
The `QualityConfig` class provides centralized configuration for the quality scoring system. It defines thresholds, weights, and behavioral parameters that control how quality is evaluated.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `min_quality` | float | 0.0 | Minimum quality threshold for inclusion |
| `max_quality` | float | 1.0 | Maximum possible quality score |
| `boost_weight` | float | varies | Weight given to quality in search ranking |
| `implicit_weight` | float | varies | Weight for implicit signal evaluation |
资料来源：[src/mcp_memory_service/quality/config.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/config.py)
### QualityScorer
The `QualityScorer` is the main orchestrator class that coordinates quality evaluation across all sub-components. It aggregates scores from different evaluation methods and produces a unified quality score.
```python
class QualityScorer:
def __init__(self, config: QualityConfig):
self.config = config
self.ranker = ONNXRankerModel()
self.evaluator = QualityEvaluator()
self.implicit_evaluator = ImplicitSignalsEvaluator()
```
**Key Responsibilities:**
- Aggregates scores from ONNX ranker, AI evaluator, and implicit signals
- Provides a unified `get_score()` interface
- Handles caching and optimization for repeated evaluations
- Manages configuration propagation to sub-components
资料来源：[src/mcp_memory_service/quality/scorer.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/scorer.py)
### ONNXRankerModel
The `ONNXRankerModel` provides fast, offline-capable quality ranking using ONNX Runtime. This model evaluates content based on learned patterns of what constitutes high-quality memory content.
**Advantages of ONNX-based ranking:**
- Runs entirely offline without external API dependencies
- Fast inference suitable for real-time evaluation
- Portable across different platforms and hardware
- No per-token costs unlike cloud-based alternatives
资料来源：[src/mcp_memory_service/quality/onnx_ranker.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/onnx_ranker.py)
### QualityEvaluator
The `QualityEvaluator` provides AI-based quality assessment, likely utilizing more sophisticated language model analysis for nuanced content quality determination.
**Evaluation Criteria:**
- Content specificity and detail level
- Actionability of information
- Temporal relevance
- Uniqueness of content
资料来源：[src/mcp_memory_service/quality/ai_evaluator.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/ai_evaluator.py)
### ImplicitSignalsEvaluator
The `ImplicitSignalsEvaluator` analyzes behavioral patterns to infer memory importance without explicit user feedback. This component detects signals that suggest a memory's value based on how it's accessed and used.
**Implicit Signals:**
- Retrieval frequency
- Retrieval timing patterns
- Context of retrieval requests
- Cross-referencing with other memories
资料来源：[src/mcp_memory_service/quality/implicit_signals.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/implicit_signals.py)
## Module Exports
All quality scoring components are exported through the main quality module interface:
```python
from mcp_memory_service.quality import (
QualityScorer,
ONNXRankerModel,
QualityEvaluator,
ImplicitSignalsEvaluator,
QualityConfig
)
```
资料来源：[src/mcp_memory_service/quality/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/__init__.py)
## API Integration
### Quality-Aware Search
The quality scoring system integrates with the search API through the `quality_boost` parameter. When performing semantic or hybrid searches, memories with higher quality scores receive ranking boosts.
**Search Parameters Related to Quality:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `quality_boost` | float | 0.0 | Weight for quality-based ranking (0.0-1.0) |
| `min_quality` | float | 0.0 | Minimum quality threshold filter |
| `include_debug` | bool | false | Include quality scoring details in response |
**Implementation in Memory Handler:**
```python
quality_boost=arguments.get("quality_boost", 0.0),
limit=limit,
include_debug=arguments.get("include_debug", False),
```
资料来源：[src/mcp_memory_service/server/handlers/memory.py:26-32](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)
### Quality Scoring in Results
The `CompactSearchResult` type includes a `score` field that represents the relevance score, which incorporates quality assessment when `quality_boost` is enabled.
**CompactMemory Score Field:**
```python
class CompactMemory(NamedTuple):
hash: str # 8-character content hash
preview: str # First 200 characters
tags: tuple[str, ...] # Immutable tags tuple
created: float # Unix timestamp
score: float # Relevance score 0-1
```
资料来源：[src/mcp_memory_service/api/types.py:48-56](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/types.py)
## Quality Actions Handler
The quality system exposes several actions through the `memory_quality` tool handler, providing programmatic access to quality operations.
### Action Types
| Action | Description | Required Parameters |
|--------|-------------|---------------------|
| `rate` | Manually rate a memory's quality | `content_hash`, `rating` |
| `analyze` | Analyze quality distribution | `min_quality`, `max_quality` |
| `maintain` | Run quality-based maintenance | varies |
| `maintain_status` | Check maintenance status | none |
### Rate Memory Action
Allows explicit user feedback on memory quality:
```python
async def handle_rate_memory(server, arguments: dict) -> List[types.TextContent]:
content_hash = arguments.get("content_hash")
rating = arguments.get("rating")
feedback = arguments.get("feedback", "")
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content_hash` | string | Yes | Hash of the memory to rate |
| `rating` | integer/string | Yes | Quality rating (converted to integer) |
| `feedback` | string | No | Optional feedback text |
资料来源：[src/mcp_memory_service/server/handlers/quality.py:47-59](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/quality.py)
### Analyze Quality Distribution
Provides statistical analysis of memory quality across the store:
```python
elif action == "analyze":
return await handle_analyze_quality_distribution(server, {
"min_quality": arguments.get("min_quality", 0.0),
"max_quality": arguments.get("max_quality", 1.0)
})
```
### Maintenance Operations
The maintain action provides automated quality-based memory management:
```python
elif action == "maintain":
return await handle_maintain(server, arguments)
elif action == "maintain_status":
return await handle_maintain_status()
```
资料来源：[src/mcp_memory_service/server/handlers/quality.py:30-38](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/quality.py)
## Workflow Diagrams
### Quality Evaluation Flow
```mermaid
graph LR
A[Incoming Memory] --> B{Is cached?}
B -->|No| C[Run ONNX Ranker]
C --> D[Run AI Evaluator]
D --> E[Run Implicit Signals]
E --> F[Aggregate Scores]
F --> G[Compute Final Quality]
G --> H[Cache Result]
H --> I[Return Score]
B -->|Yes| I
```
### Quality-Aware Search Flow
```mermaid
graph TD
A[Search Query] --> B[Semantic Search]
B --> C[Initial Results]
C --> D{quality_boost > 0?}
D -->|Yes| E[Fetch Quality Scores]
D -->|No| H[Return Results]
E --> F[Apply Quality Boost]
F --> G[Re-rank Results]
G --> H
```
## Usage Examples
### Basic Quality Evaluation
```python
from mcp_memory_service.quality import QualityScorer, QualityConfig
config = QualityConfig(min_quality=0.5, boost_weight=0.3)
scorer = QualityScorer(config)
quality_score = scorer.get_score(memory_content)
print(f"Quality score: {quality_score}")
```
### Quality-Boosted Search
When searching with quality consideration:
```python
results = await search_memories(
query="architecture decisions",
quality_boost=0.5, # Apply quality weighting
limit=10
)
```
### Manual Rating
```python
result = await handle_rate_memory(server, {
"content_hash": "abc12345",
"rating": 4,
"feedback": "Important architectural decision"
})
```
## Configuration Best Practices
### Performance vs Accuracy
| Use Case | Configuration | Rationale |
|----------|--------------|-----------|
| Real-time search | `quality_boost=0.2-0.3` | Balance relevance with performance |
| High-precision retrieval | `quality_boost=0.5-0.7` | Prioritize quality over recall |
| Maintenance/cleanup | `min_quality=0.3-0.5` | Filter low-value memories |
### Thresholds
| Memory Type | Recommended `min_quality` |
|-------------|---------------------------|
| Session summaries | 0.4 |
| Implementation details | 0.5 |
| Architectural decisions | 0.6 |
| Bug fixes | 0.3 |
| Reference documentation | 0.5 |
## Summary
The Quality Scoring System provides a comprehensive framework for evaluating and managing memory content quality in the MCP Memory Service. By combining ONNX-based offline ranking, AI-powered evaluation, and implicit behavioral signals, the system ensures that high-value memories are surfaced first while providing tools for ongoing quality maintenance.
The modular architecture allows for:
- **Scalability**: ONNX Runtime enables efficient inference at scale
- **Flexibility**: Configurable weights and thresholds for different use cases
- **Offline capability**: Core ranking works without network dependencies
- **User control**: Manual rating provides explicit feedback pathways
- **Maintenance**: Built-in tools for quality-based memory management
---
## REST API Reference
### 相关页面
相关主题：[Agent Framework Integration](#agent-frameworks), [Quick Start Guide](#quickstart)
Related Source Files
以下源码文件用于生成本页说明：
- [src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
- [src/mcp_memory_service/api/operations.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)
- [src/mcp_memory_service/web/api/mcp.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)
- [src/mcp_memory_service/server/handlers/memory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)
- [scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)
- [src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)
# REST API Reference
## Overview
The MCP Memory Service exposes a comprehensive REST API for managing semantic memories, performing advanced searches, and subscribing to real-time events. The API serves as the primary interface for external clients, web applications, and programmatic integrations that need to interact with the memory storage backend without using the MCP (Model Context Protocol) tools.
The REST API provides four major functional areas:
| Area | Description |
|------|-------------|
| **Memory Management** | Store, retrieve, list, and delete semantic memories |
| **Search Operations** | Semantic similarity, tag-based, and time-based search |
| **Real-time Events** | Server-Sent Events (SSE) for live updates |
| **MCP Protocol** | JSON-RPC interface compatible with MCP clients |
资料来源：[src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
## Architecture
The REST API is built on FastAPI and serves as a thin layer over the core `MemoryService` and storage backends. Requests flow through the API router to the appropriate handlers, which delegate business logic to shared services.
```mermaid
graph TD
A[HTTP Client] --> B[FastAPI Router]
B --> C[/api/memories]
B --> D[/api/search]
B --> E[/api/events]
B --> F[/api/mcp]
C --> G[Memory Handler]
D --> H[Search Handler]
E --> I[SSE Publisher]
F --> J[MCP Handler]
G --> K[MemoryService]
H --> K
K --> L[(SQLite + sqlite_vec)]
```
资料来源：[src/mcp_memory_service/web/api/mcp.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)
## Base Configuration
### Server Address
| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `MCP_HOST` | `0.0.0.0` | Bind address |
| `MCP_PORT` | `8080` | HTTP port |
| `MCP_MAX_RESPONSE_CHARS` | `0` (unlimited) | Response truncation limit |
资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)
## Memory Management Endpoints
### Store a Memory
Creates a new memory with automatic embedding generation.
```
POST /api/memories
```
| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| `content` | string | body | Yes | Memory content text |
| `tags` | string[] | body | No | List of tags |
| `memory_type` | string | body | No | Classification type (default: "note") |
| `metadata` | object | body | No | Custom metadata key-value pairs |
**Response:**
```json
{
"content_hash": "abc12345",
"message": "Memory stored successfully"
}
```
资料来源：[src/mcp_memory_service/api/operations.py:50-100](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)
### List All Memories
Retrieves memories with pagination and optional filtering.
```
GET /api/memories
```
| Parameter | Type | Location | Required | Default | Description |
|-----------|------|----------|----------|---------|-------------|
| `page` | integer | query | No | `1` | 1-based page number |
| `page_size` | integer | query | No | `20` | Results per page (max: 100) |
| `tags` | string | query | No | - | Comma-separated tag filter |
| `tag_match` | string | query | No | `any` | Match logic: `any` (OR) or `all` (AND) |
| `memory_type` | string | query | No | - | Filter by memory type |
| `stale_days` | integer | query | No | - | Filter memories not accessed in N days |
**Response:**
```json
{
"memories": [
{
"content": "Memory content here",
"content_hash": "abc12345",
"tags": ["tag1", "tag2"],
"memory_type": "note",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"page_size": 20,
"total_count": 150
}
}
```
资料来源：[src/mcp_memory_service/server/handlers/memory.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)
### Retrieve a Memory
Retrieves a specific memory by its content hash.
```
GET /api/memories/{hash}
```
| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| `hash` | string | path | Yes | 8-character content hash |
**Response:**
```json
{
"content": "Memory content here",
"content_hash": "abc12345",
"tags": ["architecture", "database"],
"memory_type": "reference",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z",
"metadata": {}
}
```
资料来源：[src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
### Delete a Memory
Removes a memory and its associated embeddings.
```
DELETE /api/memories/{hash}
```
| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| `hash` | string | path | Yes | 8-character content hash |
**Response:**
```json
{
"success": true,
"message": "Memory deleted successfully"
}
```
资料来源：[src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
## Search Operations
### Semantic Search
Performs vector similarity search using text embeddings.
```
POST /api/search
```
| Parameter | Type | Location | Required | Default | Description |
|-----------|------|----------|----------|---------|-------------|
| `query` | string | body | Yes | - | Search query text |
| `limit` | integer | body | No | `5` | Maximum results (1-100) |
| `tags` | string[] | body | No | - | Filter by tags |
| `threshold` | float | body | No | `0.0` | Minimum relevance score |
| `hybrid` | boolean | body | No | `false` | Enable BM25 fallback at threshold 0.4 |
**Response:**
```json
{
"memories": [
{
"content_hash": "abc12345",
"content": "Memory content...",
"tags": ["tag1"],
"relevance_score": 0.87,
"match_method": "vector"
}
],
"found": 1,
"shown": 1
}
```
资料来源：[src/mcp_memory_service/api/operations.py:100-150](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)
### Tag-Based Search
Searches memories using tags with AND/OR logic.
```
POST /api/search/by-tag
```
| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| `tags` | string[] | body | Yes | List of tags to search |
| `match_all` | boolean | body | No | `true` for AND, `false` for OR |
**Response:**
```json
{
"memories": [
{
"content": "Memory content",
"content_hash": "abc12345",
"tags": ["python", "reference"]
}
],
"total_found": 5
}
```
资料来源：[src/mcp_memory_service/server/handlers/memory.py:50-100](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)
### Time-Based Search
Natural language time-based queries for temporal memory retrieval.
```
POST /api/search/by-time
```
| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| `time_query` | string | body | Yes | Natural language time expression |
| `time_start` | float | body | No | Unix timestamp start |
| `time_end` | float | body | No | Unix timestamp end |
**Example Queries:**
| Expression | Interpretation |
|------------|----------------|
| `last week` | 7 days ago to now |
| `yesterday's architectural discussions` | Previous day |
| `between 2025-01-01 and 2025-01-31` | Date range |
资料来源：[scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)
### Find Similar Memories
Finds memories semantically similar to a specific memory by hash.
```
GET /api/search/similar/{hash}
```
| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| `hash` | string | path | Yes | Content hash of reference memory |
| `limit` | integer | query | No | Maximum similar memories to return |
**Response:**
```json
{
"reference_hash": "abc12345",
"similar": [
{
"content_hash": "def67890",
"content": "Similar memory content...",
"similarity_score": 0.92
}
]
}
```
## Real-time Events (SSE)
### Subscribe to Memory Events
Server-Sent Events stream for live memory activity.
```
GET /api/events
```
**Event Types:**
| Event | Description |
|-------|-------------|
| `memory_stored` | New memory added |
| `memory_deleted` | Memory removed |
| `memory_updated` | Memory modified |
| `embedding_complete` | Async embedding finished |
**Example SSE Payload:**
```
event: memory_stored
data: {"content_hash": "abc12345", "timestamp": "2025-01-15T10:30:00Z"}
event: memory_deleted
data: {"content_hash": "def67890", "timestamp": "2025-01-15T10:35:00Z"}
```
资料来源：[src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
### SSE Statistics
View connection statistics for SSE endpoints.
```
GET /api/events/stats
```
**Response:**
```json
{
"active_connections": 2,
"total_events_sent": 1450,
"uptime_seconds": 86400
}
```
## MCP Protocol Endpoint
The MCP-compatible JSON-RPC endpoint enables integration with MCP clients.
```
POST /api/mcp
```
### Supported Methods
| Method | Description |
|--------|-------------|
| `initialize` | Initialize MCP session, returns server capabilities |
| `tools/list` | List available MCP tools |
| `tools/call` | Execute a named MCP tool |
### Initialize Request
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {}
}
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {"tools": {}},
"serverInfo": {
"name": "mcp-memory-service",
"version": "4.1.1"
}
}
}
```
### Tools List
Returns all available MCP tools with their schemas.
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}
```
### Tool Call
Execute a named tool with arguments.
```json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "memory_search",
"arguments": {
"query": "architecture decisions",
"limit": 5
}
}
}
```
资料来源：[src/mcp_memory_service/web/api/mcp.py:20-60](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)
## Response Limiting
The API implements automatic response truncation to prevent context window overflow.
### Behavior
| Scenario | Action |
|----------|--------|
| `MCP_MAX_RESPONSE_CHARS=0` | No limit (backward compatible) |
| `MCP_MAX_RESPONSE_CHARS>0` | Truncate at memory boundaries |
| Response truncated | Include warning header |
### Truncation Metadata
When responses are truncated, the following metadata is included:
```json
{
"warning": "RESPONSE TRUNCATED: Showing 5 of 25 results (15000 of 75000 chars)",
"meta": {
"truncated": true,
"shown_results": 5,
"total_results": 25,
"shown_chars": 15000,
"total_chars": 75000,
"omitted_count": 20
}
}
```
资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:60-120](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)
## Data Models
### Memory Object
| Field | Type | Description |
|-------|------|-------------|
| `content` | string | Memory text content |
| `content_hash` | string | 8-character SHA256 hash |
| `tags` | string[] | Associated tags |
| `memory_type` | string | Classification (note, reference, decision, etc.) |
| `created_at` | ISO8601 | Creation timestamp |
| `updated_at` | ISO8601 | Last modification timestamp |
| `metadata` | object | Custom key-value pairs |
| `created_at_iso` | string | ISO format creation time |
| `updated_at_iso` | string | ISO format modification time |
### Search Result
| Field | Type | Description |
|-------|------|-------------|
| `memories` | Memory[] | Matching memories |
| `found` | integer | Total matches |
| `shown` | integer | Results returned (after limit) |
| `query_time_ms` | float | Search duration |
## Export Endpoints
### Export Memories
Export memories in text or JSON format for backup and migration.
```
GET /api/export
```
| Parameter | Type | Location | Description |
|-----------|------|----------|-------------|
| `format` | string | query | `text` or `json` (default: `text`) |
**JSON Export Format:**
```json
{
"export_metadata": {
"source_machine": "machine-name",
"export_timestamp": "2025-08-12T10:30:00Z",
"total_memories": 450,
"database_path": "/path/to/sqlite_vec.db",
"platform": "Windows",
"exporter_version": "5.0.0"
},
"memories": [
{
"content": "Memory content here",
"content_hash": "sha256hash",
"tags": ["tag1", "tag2"],
"created_at": 1673545200.0,
"updated_at": 1673545200.0,
"memory_type": "note",
"metadata": {},
"export_source": "machine-name"
}
]
}
```
资料来源：[scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)
## Performance Characteristics
| Operation | First Call | Subsequent Calls |
|------------|------------|-------------------|
| Search | ~50ms | ~5-10ms |
| Store | ~50ms | ~10-20ms |
| Health Check | ~50ms | ~5ms |
**Cost Estimate:** At $0.15/1M tokens: ~$16.43/year per 10-user deployment.
资料来源：[src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)
## API Client Library
For programmatic access, use the Python client:
```python
from mcp_memory_service.api import search, store, health
# Store a memory
hash = store("New memory", tags=["note", "important"])
# Search memories
results = search("architecture decisions", limit=5)
for m in results.memories:
print(f"{m.hash}: {m.preview[:50]}...")
# Health check
info = health()
print(f"Backend: {info.backend}, Count: {info.count}")
```
资料来源：[src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)
## Error Handling
### Standard Error Response
```json
{
"error": {
"code": -32601,
"message": "Method not found: {method}"
}
}
```
### Error Codes
| Code | Meaning |
|------|---------|
| `-32600` | Invalid Request |
| `-32601` | Method not found |
| `-32602` | Invalid params |
| `-32603` | Internal error |
| `-32000` | Storage unavailable |
## Documentation
Interactive API documentation is available at:
| URL | Format |
|-----|--------|
| `/api/docs` | Swagger UI |
| `/api/redoc` | ReDoc |
资料来源：[src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)
---
## Agent Framework Integration
### 相关页面
相关主题：[REST API Reference](#rest-api), [Quick Start Guide](#quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/agents/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/README.md)
- [docs/agents/langgraph.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/langgraph.md)
- [docs/agents/crewai.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/crewai.md)
- [docs/agents/autogen.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/autogen.md)
- [docs/agents/http-generic.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/http-generic.md)
- [docs/guides/AGENTS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/AGENTS.md)
# Agent Framework Integration
The MCP Memory Service provides comprehensive integration capabilities with various AI agent frameworks, enabling persistent semantic memory storage and retrieval across multi-agent architectures. This integration layer allows autonomous agents to maintain contextual awareness, share knowledge, and persist learning across sessions.
## Overview
The MCP Memory Service functions as a central knowledge backbone for AI agent frameworks. Rather than requiring each agent to maintain isolated memory stores, the service provides a unified semantic memory layer that can be accessed via:
- **Model Context Protocol (MCP) Tools**: Native integration for MCP-compatible agents
- **REST API**: HTTP-based access for any framework with HTTP client capabilities
- **Direct Python API**: Programmatic access for Python-native frameworks
This architecture enables agents to:
- Store discovered facts and learned patterns
- Retrieve contextually relevant memories during reasoning
- Share knowledge across agent teams
- Maintain persistent state across sessions
资料来源：[src/mcp_memory_service/api/__init__.py:1-50]()
## Supported Agent Frameworks
The MCP Memory Service integrates with the following agent frameworks through dedicated documentation and examples:
| Framework | Integration Type | Documentation |
|-----------|------------------|---------------|
| LangGraph | SDK/Graph-based | `docs/agents/langgraph.md` |
| CrewAI | Team-based agents | `docs/agents/crewai.md` |
| AutoGen | Multi-agent conversations | `docs/agents/autogen.md` |
| Custom Frameworks | HTTP/REST | `docs/agents/http-generic.md` |
资料来源：[docs/agents/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/README.md)
## Architecture for Multi-Agent Systems
```mermaid
graph TD
A[Agent Framework] --> B[MCP Memory Service API]
B --> C[Memory Management Layer]
C --> D[(SQLite-vec Storage)]
C --> E[(Cloudflare D1)]
F[Agent 1] --> B
G[Agent 2] --> B
H[Agent N] --> B
I[Embedding Generation] --> C
J[all-MiniLM-L6-v2] --> I
```
### Memory Flow in Agent Workflows
```mermaid
sequenceDiagram
participant Agent
participant MCP as MCP Memory Service
participant Storage as Vector Storage
Agent->>MCP: Store Memory (content, tags)
MCP->>MCP: Generate Embedding
MCP->>Storage: Store + Index
Storage-->>MCP: Confirm
MCP-->>Agent: Content Hash
Agent->>MCP: Semantic Search (query)
MCP->>MCP: Generate Query Embedding
MCP->>Storage: Similarity Search
Storage-->>MCP: Top-K Results
MCP-->>Agent: Relevant Memories
```
资料来源：[docs/guides/AGENTS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/AGENTS.md)
## MCP Prompt Integration
The service exposes specialized prompts for agent workflows beyond basic memory operations:
### Available Agent Prompts
| Prompt Name | Purpose | Required Arguments |
|-------------|---------|-------------------|
| `knowledge_export` | Export memories in specific formats | `format` (json/markdown/text) |
| `memory_cleanup` | Remove duplicates/outdated memories | `older_than`, `similarity_threshold` |
| `learning_session` | Store structured learning notes | `topic`, `key_points` |
资料来源：[src/mcp_memory_service/server_impl.py:150-200]()
### Prompt Argument Specifications
```python
types.PromptArgument(
name="format",
description="Export format (json, markdown, text)",
required=True
)
types.PromptArgument(
name="older_than",
description="Remove memories older than (e.g., '6 months', '1 year')",
required=False
)
types.PromptArgument(
name="similarity_threshold",
description="Similarity threshold for duplicates (0.0-1.0)",
required=False
)
```
## REST API Integration
For agent frameworks that prefer HTTP-based communication, the service provides a comprehensive REST API:
### Core Endpoints
| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/api/memories` | Store new memory |
| GET | `/api/memories` | List memories with pagination |
| GET | `/api/memories/{hash}` | Retrieve specific memory |
| DELETE | `/api/memories/{hash}` | Delete memory |
| POST | `/api/search` | Semantic similarity search |
| GET | `/api/search/similar/{hash}` | Find similar memories |
资料来源：[src/mcp_memory_service/web/app.py:50-100]()
### Response Truncation for Agent Context
To prevent context overflow in agent prompts, the response limiter intelligently truncates results:
```
[!] RESPONSE TRUNCATED: Showing 5 of 20 results
(1500 of 8000 chars).
3 result(s) omitted to prevent context overflow.
Use specific queries or hash-based retrieval for full content.
```
资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:30-60]()
## Claude Code Integration
The MCP Memory Service includes specialized hooks for Claude Code CLI integration:
### Available Claude Commands
| Command | Purpose |
|---------|---------|
| `/memory-recall` | Time-based memory retrieval using natural language |
| `/memory-search` | Tag and content search |
| `/memory-context` | Session context integration with machine source ID |
| `/memory-health` | Service health diagnostics |
资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)
### Session Hook Workflow
```mermaid
graph LR
A[Session Start] --> B[Load Relevant Memories]
B --> C[Inject into Context]
D[During Session] --> E[Track Decisions]
E --> F[Store Key Insights]
G[Session End] --> H[Save Decisions]
H --> I[Archive Insights]
I --> J[Persistent Storage]
```
## Performance Characteristics for Agents
| Metric | Value | Notes |
|--------|-------|-------|
| First Call Latency | ~50ms | Includes storage initialization |
| Subsequent Calls | ~5-10ms | Connection reused |
| Memory Overhead | <10MB | Per agent instance |
| Embedding Model | all-MiniLM-L6-v2 | 384-dimensional vectors |
| Cost (10 users) | $16.43/year | At $0.15/1M tokens |
资料来源：[src/mcp_memory_service/api/__init__.py:10-20]()
## Installation and Setup
### Automatic Installation
```bash
# Install with commands (detects Claude Code CLI)
python scripts/installation/install.py
# Force install commands
python scripts/installation/install.py --install-claude-commands
```
### Manual HTTP Integration
For custom agent frameworks:
```python
import httpx
async def store_agent_memory(content: str, tags: list[str]):
async with httpx.AsyncClient() as client:
response = await client.post(
"https://your-endpoint:8443/api/memories",
json={"content": content, "tags": tags}
)
return response.json()
```
资料来源：[docs/agents/http-generic.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/http-generic.md)
## Troubleshooting
| Issue | Solution |
|-------|----------|
| Hooks not detected | Check `ls ~/.claude/settings.json` and reinstall |
| JSON parse errors | Update to latest version with Python dict conversion |
| Connection failed | Verify `curl -k https://your-endpoint:8443/api/health` |
| Wrong directory | Move `~/.claude-code/hooks/*` to `~/.claude/hooks/` |
资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)
---
---
## Doramagic Pitfall Log
Project: doobidoo/mcp-memory-service
Summary: Found 39 potential pitfall items; 1 are high/blocking. Highest priority: security_permissions - 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare).
## 1. security_permissions · 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)
- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_d0f9028fc870496f9576de28c5355817 | https://github.com/doobidoo/mcp-memory-service/issues/950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. installation · 失败模式：installation: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)
- User impact: Developers may fail before the first successful local run: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare). Context: Observed when using node, python, docker, macos
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_dd89642370c2dba2d6aacf12756658a6 | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare), failure_mode_cluster:github_issue | fmev_07b451a0081c6435e7494e041a6641bc | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)
## 3. installation · 失败模式：installation: chore(milvus): track optional BaseStorage overrides + test coverage gaps
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: chore(milvus): track optional BaseStorage overrides + test coverage gaps
- User impact: Developers may fail before the first successful local run: chore(milvus): track optional BaseStorage overrides + test coverage gaps
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: chore(milvus): track optional BaseStorage overrides + test coverage gaps. Context: Observed when using docker
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_74209176888c160a35483f3156117496 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_d8321b2cf697c747506701fd9f641fef | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_89d7bb3a956afe53a7a303ded77ab494 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_4d3ba37fa05ae6ea3d30aa7e6acbf4a4 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps
## 4. installation · 失败模式：installation: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug
- User impact: Developers may fail before the first successful local run: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug. Context: Observed when using windows
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_b14a35b730602b08a29e3abbdfa0c377 | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug, failure_mode_cluster:github_issue | fmev_a2aed67ef427fc7f9ddeebb038420d7d | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug
## 5. installation · 失败模式：installation: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix
- User impact: Upgrade or migration may change expected behavior: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix. Context: Observed when using python
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_d0ce94252816336aa4ecbd45eeb73603 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.0 | v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix
## 6. installation · 失败模式：installation: v10.59.1 — OAuth state parameter RFC 6749 compliance fix
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v10.59.1 — OAuth state parameter RFC 6749 compliance fix
- User impact: Upgrade or migration may change expected behavior: v10.59.1 — OAuth state parameter RFC 6749 compliance fix
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.1 — OAuth state parameter RFC 6749 compliance fix. Context: Observed when using python
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_a0594e0fe855897f4612a17f520e81d4 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.1 | v10.59.1 — OAuth state parameter RFC 6749 compliance fix
## 7. installation · 失败模式：installation: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility
- User impact: Upgrade or migration may change expected behavior: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility. Context: Observed when using python
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_8a1390fb930fb3d5c55aee894e53c0e3 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.60.2 | v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility
## 8. installation · 失败模式：installation: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix
- User impact: Upgrade or migration may change expected behavior: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix. Context: Observed when using python
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_cce458b1322f9ccb8db2498d3499650d | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.63.0 | v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix
## 9. installation · 来源证据：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_…
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_all_memories'
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_da505f8e644d4dedbe7b94f2026f2c47 | https://github.com/doobidoo/mcp-memory-service/issues/981 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 10. installation · 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(milvus): track optional BaseStorage overrides + test coverage gaps
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_520e5021db184be199bf78f1b662b13c | https://github.com/doobidoo/mcp-memory-service/issues/888 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 11. installation · 来源证据：fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_99e7481daede4079a5bb8c96cba781ba | https://github.com/doobidoo/mcp-memory-service/issues/957 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 12. installation · 来源证据：fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_2027915616af406998b039c789f84c69 | https://github.com/doobidoo/mcp-memory-service/issues/938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 13. installation · 来源证据：v10.54.0 — AND/OR tag filtering for memory_search
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.54.0 — AND/OR tag filtering for memory_search
- User impact: 可能影响升级、迁移或版本选择。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_5aa57485baf04502a8291b6694828c38 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 14. installation · 来源证据：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_c50e5d07aa964a89a80ade8ee3055612 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0 | 来源类型 github_release 暴露的待验证使用条件。
## 15. configuration · 可能修改宿主 AI 配置
- Severity: medium
- Evidence strength: source_linked
- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。
- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- Evidence: capability.host_targets | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | host_targets=mcp_host, claude
## 16. configuration · 失败模式：configuration: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags...
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)
- User impact: Developers may misconfigure credentials, environment, or host setup: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`). Context: Observed when using python, linux
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_d1e6b62e41c0cf3c6d4867576ec205f2 | https://github.com/doobidoo/mcp-memory-service/issues/941 | Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)
## 17. configuration · 失败模式：configuration: [automated] Contributor activity digest
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: [automated] Contributor activity digest
- User impact: Developers may misconfigure credentials, environment, or host setup: [automated] Contributor activity digest
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [automated] Contributor activity digest. Context: Observed during version upgrade or migration.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_cdd98907ecf0813d3cca5938d053939d | https://github.com/doobidoo/mcp-memory-service/issues/937 | [automated] Contributor activity digest
## 18. configuration · 失败模式：configuration: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shippe...
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0
- User impact: Developers may misconfigure credentials, environment, or host setup: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0. Context: Observed when using python
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_886eb379e3e7ddfb3838d01f459a2a13 | https://github.com/doobidoo/mcp-memory-service/issues/959 | bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0
## 19. configuration · 失败模式：configuration: feat: cascading search fallback when semantic results are sparse
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat: cascading search fallback when semantic results are sparse
- User impact: Developers may misconfigure credentials, environment, or host setup: feat: cascading search fallback when semantic results are sparse
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat: cascading search fallback when semantic results are sparse. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_8fc694ce4bba9729e62b19e988a1d8b6 | https://github.com/doobidoo/mcp-memory-service/issues/873 | feat: cascading search fallback when semantic results are sparse
## 20. configuration · 失败模式：configuration: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgemen...
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow
- User impact: Upgrade or migration may change expected behavior: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow. Context: Observed during version upgrade or migration.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_e88b18989bddcec0f1d8e4edabb3137e | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.58.0 | v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow
## 21. configuration · 失败模式：configuration: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional
- User impact: Upgrade or migration may change expected behavior: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional. Context: Observed during version upgrade or migration.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_8d10e56924a64499b0765864db43f654 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.2 | v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional
## 22. configuration · 失败模式：configuration: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair
- User impact: Upgrade or migration may change expected behavior: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair. Context: Observed during version upgrade or migration.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_df9c592e9c921338e81c926f496f3755 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.60.1 | v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair
## 23. configuration · 来源证据：Support Kiro CLI JSONL format in memory_harvest
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support Kiro CLI JSONL format in memory_harvest
- User impact: 可能影响升级、迁移或版本选择。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_3c9e617ea7184d08ae031c4983f4787c | https://github.com/doobidoo/mcp-memory-service/issues/934 | 来源类型 github_issue 暴露的待验证使用条件。
## 24. configuration · 来源证据：bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_fdf4f21de0234532b94ed2ffe3673c4e | https://github.com/doobidoo/mcp-memory-service/issues/959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 25. capability · 能力判断依赖假设
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: 假设不成立时，用户拿不到承诺的能力。
- Suggested check: 将假设转成下游验证清单。
- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。
- Evidence: capability.assumptions | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | README/documentation is current enough for a first validation pass.
## 26. runtime · 来源证据：bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mapping + overzealous filter
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mapping + overzealous filter
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_4c07b5794f0741d8b76a3e94ca317421 | https://github.com/doobidoo/mcp-memory-service/issues/972 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 27. maintenance · 失败模式：migration: Support Kiro CLI JSONL format in memory_harvest
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: Support Kiro CLI JSONL format in memory_harvest
- User impact: Developers may hit a documented source-backed failure mode: Support Kiro CLI JSONL format in memory_harvest
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Support Kiro CLI JSONL format in memory_harvest. Context: Observed during version upgrade or migration.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_ccb1d35700dbdd7961b19ca816ab2ec2 | https://github.com/doobidoo/mcp-memory-service/issues/934 | Support Kiro CLI JSONL format in memory_harvest
## 28. maintenance · 失败模式：migration: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Se...
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix
- User impact: Developers may hit a documented source-backed failure mode: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix. Context: Observed when using python, docker
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_474dd77beac7531143e2c9c8c014d21e | https://github.com/doobidoo/mcp-memory-service/issues/938 | fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix
## 29. maintenance · 来源证据：v10.55.1 — Entity Link Storage Fix
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v10.55.1 — Entity Link Storage Fix
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_0d033317867f482985c4e395b8825cfe | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1 | 来源类型 github_release 暴露的待验证使用条件。
## 30. maintenance · 维护活跃度未知
- Severity: medium
- Evidence strength: source_linked
- Finding: 未记录 last_activity_observed。
- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。
- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | last_activity_observed missing
## 31. security_permissions · 下游验证发现风险项
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 下游已经要求复核，不能在页面中弱化。
- Suggested check: 进入安全/权限治理复核队列。
- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。
- Evidence: downstream_validation.risk_items | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium
## 32. security_permissions · 存在评分风险
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 风险会影响是否适合普通用户安装。
- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。
- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。
- Evidence: risks.scoring_risks | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium
## 33. security_permissions · 来源证据：Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_aa1db2bf08304d3db87350b8cbc8e6ca | https://github.com/doobidoo/mcp-memory-service/issues/941 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 34. security_permissions · 来源证据：[automated] Contributor activity digest
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[automated] Contributor activity digest
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_0676e682588642899da4243174241e7b | https://github.com/doobidoo/mcp-memory-service/issues/937 | 来源类型 github_issue 暴露的待验证使用条件。
## 35. security_permissions · 来源证据：feat: cascading search fallback when semantic results are sparse
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: cascading search fallback when semantic results are sparse
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_274fcdb5c1ed4290ac86171131d9db90 | https://github.com/doobidoo/mcp-memory-service/issues/873 | 来源类型 github_issue 暴露的待验证使用条件。
## 36. security_permissions · 来源证据：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_60ded0d65a2c417e9ce3c9ed7501cbad | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.52.0 | 来源类型 github_release 暴露的待验证使用条件。
## 37. security_permissions · 来源证据：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_42c0d95dd5b247d79790b6f92024a048 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.53.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 38. maintenance · issue/PR 响应质量未知
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: 用户无法判断遇到问题后是否有人维护。
- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。
- Guardrail action: issue/PR 响应未知时，必须提示维护风险。
- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | issue_or_pr_quality=unknown
## 39. maintenance · 发布节奏不明确
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。
- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。
- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | release_recency=unknown