Hippocampus

海马体：大脑中负责记忆和空间导航的核心区域

为 Hermes Agent 提供生产级本地记忆系统。

核心特性

• ✅ 混合检索：向量搜索 + BM25 关键词搜索 + RRF 融合
• ✅ 完全本地：使用 Ollama 做嵌入和提取，零 API 成本
• ✅ 分层记忆：Core/Working/Peripheral 三层，自动衰减进化
• ✅ 智能提取：自动从对话中提取偏好、事实、决策
• ✅ 零 Token 成本：所有操作都在本地完成

智能记忆切换机制

重要特性

当启用此技能时，会自动接管 Hermes 的记忆功能：

• ✅ 本技能激活 → 自动禁用 Hermes 系统记忆
• ✅ 本技能关闭 → 自动恢复 Hermes 系统记忆
• ✅ 避免两个记忆系统冲突

工作原理

1. 技能激活时：

   • 通过配置禁用 Hermes 的 memory tool
   • 所有记忆操作通过本技能的 API 完成
   • 存储：LanceDB（本地向量数据库）

2. 技能关闭时：

   • 重新启用 Hermes 的 memory tool
   • 恢复到默认记忆系统

快速开始

前置条件

# 1. 安装 Python 依赖
pip install lanced>=0.26.2 numpy pyarrow requests

# 2. 确保运行 Ollama
ollama serve  # 或使用已有的 Ollama 服务

# 3. 拉取嵌入模型
ollama pull nomic-embed-text-v2-moe

启用技能

方式 1：通过 Python 脚本直接使用

from memory import MemoryStore, MemoryRetriever
from memory.models import MemoryCategory, RecallQuery

# 初始化组件
store = MemoryStore(storage_path="./data/memory")
retriever = MemoryRetriever(store=store)

# 添加记忆
store.add(
    text="用户偏好使用 tab 缩进",
    category=MemoryCategory.PREFERENCE,
    importance=0.9
)

# 召回记忆
query = RecallQuery(text="用户编程偏好", limit=3)
results = retriever.recall(query)

for result in results:
    print(f"[{result.entry.category.value}] {result.entry.text}")

方式 2：通过 subprocess 调用（推荐）

# 在 Python 脚本目录运行
cd /mnt/d/github/Hippocampus
python -c "
from memory import MemoryStore
store = MemoryStore()
store.add(text='测试记忆')
"

API 参考

MemoryStore（存储管理）

from memory import MemoryStoreHippocampus, MemoryCategory, MemoryTier

# 初始化
store = MemoryStore(storage_path="./data/memory")

# 添加记忆
memory_id = store.add(
    text="用户偏好使用 2-space 缩进",
    category=MemoryCategory.PREFERENCE,
    importance=0.9,
    tier=MemoryTier.CORE
)

# 获取记忆
entry = store.get(memory_id)

# 更新记忆
store.update(
    memory_id=memory_id,
    text="用户偏好改为 4-space 缩进",
    importance=0.95
)

# 删除记忆
store.delete(memory_id)

# 列出记忆
memories = store.list_all(limit=10)

# 关闭上数据库
store.close()

MemoryRetriever（混合检索）

from memory import MemoryRetrieverHippocampus, RecallQuery, MemoryCategory

# 初始化
retriever = MemoryRetrieverHippocampus(store=store)

# 召回记忆
query = RecallQuery(
    text="用户编程偏好",
    limit=5,
    category=MemoryCategory.PREFERENCE,  # 可选：按分类过滤
    min_score=0.5  # 最小相似度阈值
)

results = retriever.recall(query)

for result in results:
    print(f"评分: {result.score:.4f}")
    print(f"内容: {result.entry.text}")
    print(f"分类: {result.entry.category.value}")
    print(f"向量分: {result.vector_score:.4f}")
    print(f"BM25分: {result.bm25_score:.4f}")
    print(f"新近度: {result.recency_boost:.4f}")

SmartExtractor（智能提取）

from memory import SmartExtractor

# 初始化
extractor = SmartExtractor()

# 从对话中提取
messages = [
    {"role": "user", "content": "我喜欢用 tab 缩进"},
    {"role": "assistant", "content": "好的，记住了"},
    {"role": "user", "content": "项目使用 Python"}
]

memories = extractor.extract_from_conversation(messages)

for memory in memories:
    print(f"[{memory.category.value}] {memory.text}")
    print(f"重要性: {memory.importance}")

配置选项

检索配置

{
    "vector_weight": 0.7,      # 向量搜索权重（0-1）
    "bm25_weight": 0.3,       # BM25 搜索权重（0-1）
    "min_score": 0.3,          # 最小相似度阈值（0-1）
    "filter_noise": True,        # 过滤噪声记忆
    "candidate_pool_size": 20,   # RRF 融合候选池大小
}

记忆衰减配置

{
    "decay_enabled": True,          # 启用记忆衰减
    "decay_half_life_days": 30,       # 衰减半衰期（天）
    "reinforcement_factor": 0.5,   # 访问强化因子（0-2）
    "max_half_life_multiplier": 3  # 最大半衰期倍数
}

数据结构

记忆分类（6类）

分类	说明	示例
PREFERENCE	用户偏好	缩进用 tab、使用特定 IDE
FACT	事实信息	项目使用 Python、数据库是 PostgreSQL
DECISION	决策记录	选择方案 A 而不是方案 B
ENTITY	实体信息	用户名是张三、邮箱是 xxx
EVENT	事件记录	昨天完成了项目部署
CASE	案例模式	某类问题的解决方案

记忆层级（3层）

层级	说明	重要性范围
CORE	核心记忆	0.8-1.0（最重要）
WORKING	工作记忆	0.6-0.8（常用）
PERIPHERAL	外围记忆	0.0-0.6（次要）

使用场景

场景 1：跨会话记忆

# 用户对话
"用户：我喜欢用 tab 缩进"
"助手：好的，我记住了"

# 下次会话（新会话）
"用户：项目怎么缩进的？"

# 自动召回到记忆
store.add(text="用户偏好使用 tab 缩进", category=MemoryCategory.PREFERENCE)
# → "助手：根据之前的信息，你偏好使用 tab 缩进"

场景 2：智能提取

# 多轮对话后自动提取
messages = [
    {"role": "user", "content": "我们选了方案 A"},
    {"role": "assistant", "content": "明白了，我会记下来"},
    {"role": "user", "content": "方案 A 的优点是..."}
]

# 自动提取关键信息
memories = extractor.extract_from_conversation(messages)
# → 可能提取：
#   "项目选择了方案 A" (DECISION, 重要性 0.9)
#   "方案 A 的优点是..." (FACT, 重要性 0.8)

场景 3：混合检索

# 用户查询
query = "我的编程偏好是什么？"

# 混合检索（向量相似度 + 关键词匹配）
results = retriever.recall(RecallQuery(text=query, limit=5))

# 返回最相关的记忆，按综合评分排序
for result in results:
    # 综合评分 = 向量分 * 0.7 + BM25分 * 0.3 + 新近度提升
    print(f"{result.entry.text} (评分: {result.score:.4f})")

性能指标

指标	典型值	说明
嵌入延迟	50-200ms	Ollama 嵌入时间
检索延迟	100-500ms	向量搜索 + BM25 搜索
存储大小	10-100MB	取决于记忆数量
记忆数量	100-10000 条	取决于使用时长
召回准确率	85-95%	混合检索提升准确率

故障排除

问题 1：Ollama 连接失败

症状：ConnectionError: Ollama 连接失败

解决：

# 检查 Ollama 是否运行
curl http://host.docker.internal:11434/api/tags

# 如果在 WSL2，使用 host.docker.internal
export OLLAMA_HOST=0.0.0.0
ollama serve

问题 2：LanceDB 依赖缺失

症状：ModuleNotFoundError: No module named 'lancedb'

解决：

pip install lancedb>=0.26.2

问题 3：向量维度不匹配

症状：嵌入维度不一致导致检索失败

解决：

# 检查嵌入维度
embedder = OllamaEmbedder()
dim = embedder.get_embedding_dim()
print(f"嵌入维度: {dim}")  # 应该是 768 或 1024

# 确保使用相同的模型
embedder = OllamaEmbedder(model="nomic-embed-text-v2-moe")  # 768-dim
# 或
embedder = OllamaEmbedder(model="mxbai-embed-large")  # 1024-dim

最佳实践

1. 使用分类标签：为记忆添加分类（PREFERENCE/FACT/DECISION）
2. 设置合理的重要性：核心记忆 0.8-1.0，外围记忆 0.0-0.6
3. 定期维护：删除低价值或过期的记忆
4. 监控衰减：调整衰减参数以优化召回率
5. 平衡权重：根据实际效果调整向量/BM25 权重

高级功能

记忆统计

stats = store.get_stats()
print(f"总记忆数: {stats.total_memories}")
print(f"活跃记忆: {stats.active_memories}")
print(f"已过期: {stats.expired_memories}")
print(f"平均重要性: {stats.average_importance}")

批量操作

# 批量添加
memories = [
    ("记忆1", MemoryCategory.FACT, 0.8),
    ("记忆2", MemoryCategory.PREFERENCE, 0.9)
]

for text, category, importance in memories:
    store.add(text=text, category=category, importance=importance)

# 批量检索
queries = ["查询查询", "查询2", "查询3"]
for query in queries:
    results = retriever.recall(RecallQuery(text=query))
    print(f"{query}: {len(results)} 条结果")

项目信息

• 版本：0.1.0
• 名称：Hippocampus（海马体）
• 作者：Hermes AI
• 协议：MIT
• 存储：LanceDB (向量数据库）
• 嵌入：Ollama (本地模型)
• 目标：为 Hermes Agent 提供生产级本地记忆系统

相关链接

• GitHub 仓库：https://github.com/zjq12333/Hippocampus
• 灵感来源：https://github.com/CortexReach/memory-lancedb-pro
• Ollama：https://ollama.com/
• LanceDB：https://lancedb.com/

总结

Hippocampus 是一个专为 Hermes Agent 设计的本地记忆系统：

✅ 核心优势：

• 完全本地运行，零 API 成本
• 混合检索，召回准确率高
• 智能提取，自动学习
• 记忆衰减，自动优化

✅ 智能切换：

• 激活时自动接管 Hermes 记忆
• 关闭时自动恢复 Hermes 记忆
• 避免系统冲突

✅ 易于使用：

• 简单的 Python API
• 清晰的数据结构
• 完善的文档

开始使用：

1. 安装依赖：pip install -r requirements.txt
2. 运行测试：python tests/test_hippocampus.py
3. 集成到你的工作流

---

Hippocampus - 让 AI 像人类一样拥有长期记忆