AI导哈

持久记忆检索系统

Hippocampus是一个为大型语言模型提供的持久记忆检索系统，支持通过MCP或REST API访问，提供基于PostgreSQL和pgvector的三层长期记忆存储。

  • by hherb
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 hherb/hippocampus

使用说明

海马体

用于LLM的持久内存检索系统，可通过MCP或REST API访问。

海马体为LLM提供了三层长期记忆，由 PostgreSQL+pgvector：

  • 情景记忆 --带时间戳的向量嵌入交互记录 用于语义检索（对话、观察、事件）
  • 语义记忆/知识图谱 --提取的实体和关系 从剧集中，与矢量搜索相关存储
  • 反射/元记忆 --定期总结、见解、矛盾 跟踪和人为管理的修订建议

建筑

┌─────────────┐  ┌─────────────┐
│  MCP Client │  │  REST Client│
│ (Claude etc) │  │ (dashboard) │
└──────┬──────┘  └──────┬──────┘
       │ stdio/SSE      │ HTTP
       ▼                ▼
┌─────────────┐  ┌─────────────┐
│  MCP Server │  │  FastAPI    │
└──────┬──────┘  └──────┬──────┘
       └────────┬───────┘
                ▼
       ┌────────────────┐
       │ Memory Manager │
       ├────────────────┤
       │ Episodic       │
       │ Semantic (KG)  │
       │ Reflection     │
       └───────┬────────┘
          ┌────┴────┐
          ▼         ▼
   ┌──────────┐ ┌────────┐
   │PostgreSQL│ │ Ollama │
   │+ pgvector│ │embeddings│
   └──────────┘ └────────┘

先决条件

  • Python 3.11+
  • PostgreSQL 15+ pg向量 扩展
  • 奥拉玛 使用嵌入模型在本地运行

快速开始

# 1. Install
pip install -e .

# 2. Pull the embedding model
ollama pull nomic-embed-text-v2-moe

# 3. Create the database
createdb hippocampus
# Ensure pgvector is installed: CREATE EXTENSION vector;

# 4. Initialize the schema
hippocampus init-db

# 5a. Run the MCP server (stdio — for Claude Desktop / Claude Code)
hippocampus mcp

# 5b. Run the MCP server for a specific owner/agent
hippocampus mcp --owner agent-alice

# 5c. Run the MCP server (SSE — for remote clients)
hippocampus mcp --transport sse

# 5d. Run the REST API (serves all owners; owner_id is a query parameter)
hippocampus api

配置

所有设置都是通过环境变量进行的 HIPPOCAMPUS_ 前缀：

变量 默认值 描述
HIPPOCAMPUS_DB_URL postgresql://localhost:5432/hippocampus PostgreSQL连接URL
HIPPOCAMPUS_OLLAMA_URL http://localhost:11434 Ollama API基础URL
HIPPOCAMPUS_EMBEDDING_MODEL nomic-embed-text-v2-moe Ollama嵌入模型
HIPPOCAMPUS_EMBEDDING_DIMENSIONS 768 嵌入向量维度
HIPPOCAMPUS_EMBEDDING_PREFIX true 使用任务类型前缀（nomic模型）
HIPPOCAMPUS_API_HOST 127.0.0.1 REST API绑定主机
HIPPOCAMPUS_API_PORT 8420 REST API端口
HIPPOCAMPUS_MCP_SSE_HOST 127.0.0.1 MCP SSE绑定主机
HIPPOCAMPUS_MCP_SSE_PORT 8421 MCP SSE端口
HIPPOCAMPUS_DEFAULT_OWNER default MCP服务器的默认所有者/租户

MCP工具

当通过MCP连接时，LLM可以访问这些工具：

情景记忆

  • remember --存储新内存
  • recall --记忆的语义搜索
  • recall_recent --按时间检索最近的记忆

知识图谱

  • learn_entity --添加/更新实体
  • learn_relation --添加实体之间的关系（自动创建实体）
  • find_entities --按语义或文本搜索实体
  • query_relations --查询关系
  • explore_connections --从实体遍历BFS图

反思

  • reflect --创建总结、见解或模式观察
  • search_reflections --反思的语义搜索

人工监督

  • propose_revision --提出一种用于人工评审的知识图更改
  • pending_revisions --列出等待批准的提案

多租户技术

海马支持多个孤立的记忆空间。每个所有者（用户、代理、用户）， 组织）具有完全独立的情景记忆、知识图、行为模式、行为模式和行为模式， 反思和修订建议。

  • MCP服务器：每个实例为一个所有者服务，通过设置 --owner 旗帜或 HIPPOCAMPUS_DEFAULT_OWNER env var.运行多个实例 业主。
  • REST API：一个实例为所有所有者服务。每个端点都需要 owner_id 租户隔离的查询参数。

REST API

完整的REST API可在 http://localhost:8420/docs （Swagger UI） 跑步 hippocampus api。所有端点都需要 ?owner_id=<id> 对于租户 范围界定。

Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "hippocampus": {
      "command": "hippocampus",
      "args": ["mcp", "--owner", "my-agent"]
    }
  }
}

许可证

GNU Affero通用公共许可证v3（AGPL-3.0）

相关 MCP