一款面向生产环境的模型上下文协议（MCP）服务器，用于语义记忆管理，使人工智能代理能够跨会话存储、检索和管理上下文知识。

** 📖 系统提示可用**：请参阅SYSTEM_PROMPT.md，获取关于如何指导AI模型有效使用该记忆系统的全面指南。该提示帮助模型理解何时以及如何使用记忆工具，尤其是在主动记忆检索方面。

特色

核心能力

• TypeScript - 严格模式下的全类型安全
• PostgreSQL + pgvector - 带HNSW索引的向量相似性搜索
• Kysely ORM - 类型安全SQL查询
• 本地嵌入 - 使用Transformers.js（无API调用）
• 智能缓存 - Redis + 内存备份，实现极快性能
• 多代理支持 - 用户上下文隔离
• 令牌高效 - 从响应中移除嵌入

高级内存管理

• 图关系 - 丰富的关系类型（引用、矛盾、支持、延伸、原因、前置等）
• 图遍历 - 带有深度限制和滤波的BFS/DFS算法

MCP AI Memory

A production-ready Model Context Protocol (MCP) server for semantic memory management that enables AI agents to store, retrieve, and manage contextual knowledge across sessions.

📖 System Prompt Available: See SYSTEM_PROMPT.md for a comprehensive guide on how to instruct AI models to use this memory system effectively. This prompt helps models understand when and how to use memory tools, especially for proactive memory retrieval.

Features

Core Capabilities

• TypeScript - Full type safety with strict mode
• PostgreSQL + pgvector - Vector similarity search with HNSW indexing
• Kysely ORM - Type-safe SQL queries
• Local Embeddings - Uses Transformers.js (no API calls)
• Intelligent Caching - Redis + in-memory fallback for blazing fast performance
• Multi-Agent Support - User context isolation
• Token Efficient - Embeddings removed from responses

Advanced Memory Management

• Graph Relationships - Rich relationship types (references, contradicts, supports, extends, causes, precedes, etc.)
• Graph Traversal - BFS/DFS algorithms with depth limits and filtering
• Memory Decay - Automatic lifecycle management with exponential decay
• Memory States - Active, dormant, archived, and expired states
• Preservation - Protect important memories from decay
• Soft Deletes - Data recovery with deleted_at timestamps
• Clustering - Automatic memory consolidation
• Compression - Automatic compression of archived memories

Prerequisites

• Node.js 18+ or Bun
• PostgreSQL with pgvector extension
• Redis (optional - falls back to in-memory cache if not available)

Installation

NPM Package (Recommended for Claude Desktop)

npm install -g mcp-ai-memory

From Source

1. Install dependencies:

bun install

2. Set up PostgreSQL with pgvector:

CREATE DATABASE mcp_ai_memory;
\c mcp_ai_memory
CREATE EXTENSION IF NOT EXISTS vector;

3. Create environment file:

# Create .env with your database credentials
touch .env

4. Run migrations:

bun run migrate

Usage

Development

bun run dev

Production

bun run build
bun run start

Troubleshooting

Embedding Dimension Mismatch Error

If you see an error like:

Failed to generate embedding: Error: Embedding dimension mismatch: Model produces 384-dimensional embeddings, but database expects 768

This occurs when the embedding model changes between sessions. To fix:

1. Option 1: Reset and Re-embed (Recommended for new installations)

   # Clear existing memories and start fresh
   psql -d your_database -c "TRUNCATE TABLE memories CASCADE;"