hippocampus (Karrolcia)

海马体

AI通用内存。一台服务器，每个平台。

你的AI不应该仅仅因为你切换了应用程序就忘记你是谁。

______________________________________________________________________

Hippocampus是一个开源、自托管的MCP内存服务器。部署一次。将其连接到克劳德、ChatGPT、双子座、光标、困惑——任何会说MCP的东西。告诉一个AI一个项目决策，其他AI都已经知道了。

的问题

每个AI平台都会隔离您的上下文：

• Claude.ai内存在Claude Code中不起作用
• Claude Code的Claude.md文件在ChatGPT中不起作用
• ChatGPT的内存在Gemini中不起作用
• 他们谁也不说话

你不断地重复自己。上下文丢失。每次切换工具时，连续性都会中断。

运作原理

Claude.ai ────────────┐
Claude Code ──────────┤
Claude Desktop ───────┤
ChatGPT ──────────────┼── MCP ──▶  Hippocampus
Gemini CLI ───────────┤            (your server)
Cursor / Windsurf ────┤
Perplexity ───────────┘

主控程序 （模型上下文协议）是每个主要AI平台都采用的开放标准。Hippocampus是一个远程MCP服务器，通过Streamable HTTP公开内存工具-- remember, recall, forget还有八个。任何支持MCP的AI客户端都可以连接。

数据模型：包含实体、观察和关系的知识图。通过局部嵌入进行语义搜索。使用SQLCipher（AES-256）对整个数据库进行静态加密，包括嵌入向量 泄漏原始文本.

5分钟后试试

你需要安装Node.js 18+。

1.克隆并安装

git clone https://github.com/karrolcia/hippocampus.git
cd hippocampus
npm install

2.创建您的 .env 文件

cp .env.example .env

打开 .env 并设置您的密码（这将加密数据库）：

HIPPO_PASSPHRASE=any-secret-phrase-you-want

这是唯一需要的值。其他一切都有违约。

3.启动服务器

npm run dev

您应该看到：

Hippocampus starting on http://0.0.0.0:3000
MCP endpoint: http://0.0.0.0:3000/mcp

嵌入模型（约80MB）在第一次运行时会自动下载——第一次需要一分钟。

4.确认它还活着

curl http://localhost:3000/health

预期响应：

{"status":"ok","version":"0.3.1"}

5.连接克劳德代码

claude mcp add hippocampus --transport http http://localhost:3000/mcp

6.试试看

打开Claude Code会话并说：

请记住，我最喜欢的语言是TypeScript，我使用Hono作为我的web框架。

然后在新的会话中：

你对我的技术偏好了解多少？

如果它带着TypeScript和Hono回来，它就会工作。你的AI现在有持久的记忆。

部署到服务器

当地人非常适合尝试。要在所有AI工具中使用Hippocampus——Claude.AI、ChatGPT、Gemini、移动设备——你需要它在带有HTTPS的公共URL上运行。

你需要什么

• VPS（Hetzner CX22，每月约4欧元就足够了——欧盟司法管辖区，GDPR）
• 指向VPS的域（或子域）
• 约20分钟

步骤1：设置服务器

SSH到您的VPS并安装Docker：

# Firewall
ufw default deny incoming && ufw default allow outgoing
ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp
ufw enable

# Install Docker
curl -fsSL https://get.docker.com | sh

第二步：指向您的域名

在DNS提供商中添加A记录：

Type: A
Name: hippo            (or whatever subdomain you want)
Value: 

DNS传播通常需要几分钟。在继续之前，请验证它是否已解决：

dig hippo.yourdomain.com +short
# Should return your VPS IP

步骤3：配置

git clone https://github.com/karrolcia/hippocampus.git
cd hippocampus
chmod +x setup.sh
./setup.sh

该脚本询问您的域、用户名和密码，然后写入 .env 和 Caddyfile 为你。不需要Node.js。

Caddy通过Let's Encrypt自动处理TLS证书。

Manual setup (if you prefer)

cp .env.example .env

生成密码和OAuth密码哈希：

# Generate a random passphrase — save this in your password manager
openssl rand -base64 32

# Generate a hash of the password you'll use to log in
# Replace 'your-password' with your actual password
echo -n 'your-password' | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '='

编辑 .env 具有所有必需值：

HIPPO_PASSPHRASE=

HIPPO_OAUTH_ISSUER=https://hippo.yourdomain.com
HIPPO_OAUTH_USER=admin
HIPPO_OAUTH_PASSWORD_HASH=

编辑 Caddyfile --替换第一行上的域：

hippo.yourdomain.com {

步骤4：启动并验证

docker compose up -d

等待约30秒，让容器启动，Caddy获得证书，然后：

curl https://hippo.yourdomain.com/health

预期响应：

{"status":"ok","version":"0.3.1"}

如果您遇到证书错误，DNS可能尚未传播。请等待几分钟，然后重试。

第五步：连接你的人工智能工具

现在您的服务器已经上线，请连接您使用的每个平台。

克劳德代码：

claude mcp add hippocampus --transport http https://hippo.yourdomain.com/mcp

Claude-.ai（浏览器+移动设备）：

设置>集成>添加自定义集成>输入服务器URL：

https://hippo.yourdomain.com/mcp

您将被重定向到使用您在步骤3中配置的用户名和密码登录。

克劳德桌面：

添加到MCP配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "hippocampus": {
      "url": "https://hippo.yourdomain.com/mcp"
    }
  }
}

ChatGPT（网络+移动）：

设置>应用程序>开发人员模式>创建新应用程序>将服务器URL设置为 https://hippo.yourdomain.com/mcp

Gemini CLI：

增添 ~/.gemini/settings.json:

{
  "mcpServers": {
    "hippocampus": {
      "uri": "https://hippo.yourdomain.com/mcp"
    }
  }
}

光标/风帆/VS代码：

添加到MCP配置文件中：

{
  "mcpServers": {
    "hippocampus": {
      "url": "https://hippo.yourdomain.com/mcp"
    }
  }
}

验证： 打开任何连接的平台，让你的AI记住一些东西。切换到另一个平台并要求它回忆。如果它跨平台工作，你就完成了。

替代品：Fly.io

如果你不想管理VPS。约5美元/月。

git clone https://github.com/karrolcia/hippocampus.git
cd hippocampus

fly launch                # Creates app + Dockerfile detected automatically
fly volumes create hippo_data --size 1

编辑生成的 fly.toml --添加卷装载，以便数据库在部署中保持不变：

[mounts]
  source = "hippo_data"
  destination = "/data"

生成您的秘密——将这两个值保存在密码管理器中：

# Generate passphrase (save this — you lose your database without it)
openssl rand -base64 32

# Generate hash of your login password (replace 'your-password')
echo -n 'your-password' | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '='

将它们设置为飞行机密并部署：

fly secrets set HIPPO_PASSPHRASE=
fly secrets set HIPPO_OAUTH_ISSUER=https://.fly.dev
fly secrets set HIPPO_OAUTH_USER=admin
fly secrets set HIPPO_OAUTH_PASSWORD_HASH=

fly deploy

验证：

curl https://.fly.dev/health

Fly会自动处理HTTPS。使用连接您的AI工具 https://.fly.dev/mcp 作为服务器URL。

替代方案：家庭服务器+Cloudflare隧道

自由，最大限度的控制。在家里的任何机器上运行Hippocampus，并通过以下方式暴露它 Cloudflare隧道 --无需端口转发，也不需要静态IP。

# On your home machine
git clone https://github.com/karrolcia/hippocampus.git
cd hippocampus
cp .env.example .env

编辑 .env --设置密码和OAuth变量（跳过 setup.sh 这里——它配置了Caddy，而Cloudflare Tunnel不需要它）：

# Generate values
openssl rand -base64 32                # → HIPPO_PASSPHRASE
echo -n 'your-password' | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '='  # → HIPPO_OAUTH_PASSWORD_HASH

HIPPO_PASSPHRASE=
HIPPO_OAUTH_ISSUER=https://hippo.yourdomain.com
HIPPO_OAUTH_USER=admin
HIPPO_OAUTH_PASSWORD_HASH=

docker compose up -d hippocampus   # only hippocampus — Caddy not needed

# Install cloudflared and create a tunnel
cloudflared tunnel create hippocampus
cloudflared tunnel route dns hippocampus hippo.yourdomain.com

创建 ~/.cloudflared/config.yml:

tunnel: hippocampus
ingress:
  - hostname: hippo.yourdomain.com
    service: http://localhost:3000
  - service: http_status:404

启动隧道：

cloudflared tunnel run hippocampus

您负责正常运行时间和物理安全。看 安全.md 为了权衡利弊。

工具

人工智能自然地调用这些工具。你不需要手动管理内存——你只需与你的人工智能交谈，它就会记住。

扩散激活

当你 recall 随着 spread: true，海马体不仅返回直接匹配，它还跟踪从匹配实体中跳出来的关系，并根据您的查询对它们的观察结果进行评分。相关的观测值得分较低（衰减0.5倍），因此它们在相关时会浮出水面，但不会淹没直接命中。适用于涉及多个相关主题的问题。

矛盾检测

consolidate 随着 mode: "contradictions" 找到谈论相同事情（高嵌入相似性）但说不同事情（低单词重叠）的观察对。不需要LLM——纯嵌入数学加Jaccard比较。查看标记的配对，并决定保留什么。

新颖性评分

每 remember 呼叫返回a novelty 通过SVD子空间投影计算的分数（0-1）。成对余弦检查忽略了聚合冗余——五个具有适度个体重叠的观测值可以共同解释一个新的观测值。子空间投影同时与所有现有观测值进行比较。当新颖性降至0.1以下时，响应会警告信息可能已经被捕获。

近匹配检测

当 remember 存储新的观测值时，它会报告重叠的现有观测值（余弦相似度0.5-0.85），即“明显不同”和“接近重复”之间的区域。人工智能在响应中看到这些，可以立即合并，而不是等待一批 consolidate 无需额外计算：去重扫描已经与所有实体嵌入进行了比较。

睡眠模式

consolidate 随着 mode: "sleep" 运行批处理生命周期分析——对知识图进行通宵碎片整理。使用SVD杠杆分数结合时间信号将旧观测值分为三类：

• 压缩：冗余+旧+召回。其他地方捕获的信息，可以安全合并。
• 修剪：不记得了+老了。突触从未激活——删除候选者。
• 刷新：积极使用+独特+陈旧。人工智能继续提供这些服务，但实体上存在更新的信息。重新整合候选人。

退货 information_rank 和 redundancy_ratio 每个实体进行结构诊断。人工智能使用现有工具对结果进行操作-- merge 为了压缩， forget 对于西梅， update 刷新。

再巩固提示

当 recall 返回自以来收到更新信息的实体上超过30天的观测值，这些观测值已被标记 stale: true每次检索时都进行轻量级的日期比较，无需进行嵌入计算。AI会看到该标志，并可以决定是更新还是保持观察不变。

跨平台老化检测

你周一告诉克劳德你的项目堆栈。星期三，你转到了双子座。Gemini的缓存上下文是否仍然是最新的？每个实体都有一个 version_hash --SHA-256的观测内容。AI缓存此哈希，然后调用 check_version 问“有什么变化吗？”而不重新获取所有内容。一个轻量级的元数据调用，而不是重新读取整个实体。

所有变异工具在写入后都会返回新的哈希值。所有阅读工具都将其包含在响应中。AI总是有一个新的哈希值要缓存——没有额外的往返。

入职

新数据库启动时很冷—— hippocampus://context 资源显示了指导，提示人工智能捕捉它已经知道的关于你的信息（身份、项目、偏好）。一旦存在5+个观察结果，指导就会消失，完整的知识图谱就会接管。

为了系统地提取第一会话 onboard 该工具返回一个结构化的提示，人工智能会遵循该提示——查找什么、已经存储了什么、使用什么格式。该工具本身不存储任何东西；它给人工智能一份清单，让它做自己擅长的事情。每个平台都使用自己的上下文进行提取。

配置

安全

• 通过SQLCipher进行AES-256数据库加密（文本、嵌入、索引——一切）
• OAuth 2.1与PKCE用于远程访问
• 输入验证：50000个字符/内存，200个字符/实体名称
• 所有端点的速率限制
• PRAGMA secure_delete = ON --被遗忘的记忆是零的，而不仅仅是没有联系的
• 非root Docker， cap_drop: ALL，只读文件系统
• CORS仅限于已知的AI平台来源
• 没有外部API调用-嵌入通过Transformers.js本地运行

看 安全.md 完整的威胁模型和架构。

OAuth——幕后发生了什么

当您连接Claude.ai、ChatGPT或其他基于浏览器的平台时，它们会使用OAuth 2.1向您的服务器进行身份验证。Hippocampus包含一个自包含的OAuth服务器，不需要外部身份验证提供者。

以下是在Claude.ai中单击“连接”时发生的情况：

1. Claude.ai在您的服务器上自动注册为客户端（动态客户端注册，RFC 7591）
2. 您被重定向到服务器上的登录页面
3. 您从以下位置输入用户名和密码 .env
4. 您的服务器会发出一个短期访问令牌（1小时）和一个刷新令牌（30天）
5. Claude.ai使用MCP请求的访问令牌，到期时自动刷新

三 .env 启用此功能的变量：

• HIPPO_OAUTH_ISSUER -服务器的公共URL（告诉Hippocampus打开OAuth）
• HIPPO_OAUTH_USER --您的登录用户名
• HIPPO_OAUTH_PASSWORD_HASH --密码的SHA-256哈希（服务器从不存储明文密码）

对于本地开发，您可以通过设置完全跳过OAuth HIPPO_TOKEN 在 .env 并将其作为不记名代币传递。

贡献

建筑

src/
├── index.ts              # Hono server, MCP Streamable HTTP transport
├── config.ts             # Environment config with Zod validation
├── mcp/
│   ├── server.ts         # MCP tool registration (11 tools)
│   └── tools/            # remember, recall, forget, update, merge, merge_entities, context, consolidate, export, check_version, onboard
├── db/
│   ├── index.ts          # SQLCipher initialization
│   ├── schema.ts         # Schema + migrations
│   ├── entities.ts       # Entity CRUD
│   ├── observations.ts   # Observation CRUD + keyword search
│   └── relationships.ts  # Relationship CRUD + BFS graph traversal
├── embeddings/
│   ├── embedder.ts       # Local embeddings (all-MiniLM-L6-v2) + semantic search
│   └── subspace.ts       # SVD novelty scoring + redundancy analysis
└── auth/
    └── oauth.ts          # Self-contained OAuth 2.1 server

堆栈： Node.js、TypeScript、Hono、MCP SDK、SQLCipher、Transformers.js

运行测试

# Unit + integration tests
npm test

# Full end-to-end smoke test (real embeddings, temp encrypted DB)
HIPPO_PASSPHRASE=test HIPPO_DB_PATH=/tmp/hippo-test.db npx tsx test-all-tools.ts

平台兼容性

许可证

AGPL-3.0——免费使用、修改和自托管。如果您将修改后的版本作为网络服务运行，则必须在相同的许可证下开源您的更改。

支持

如果海马对你有用， 给我买杯咖啡.

开源。永远自由。没有托管版本。没有SaaS。