fleg45/memoria-framework

Memoria

通用 AI Agent 记忆框架 —— 记忆不是检索，是分流。

大多数 Agent 记忆框架把记忆当检索问题解决：召回一批，塞回 prompt。Memoria 不一样——它按类型把每条记忆分流到它该去的地方：事实进参考信息，偏好进用户画像，技能注册成工具，情绪影响策略，规则变成约束。Agent 跨会话记住的，不只是「更多记忆」，而是「记忆去对了地方」。

安装

pip install memoria-framework

可选扩展：

| Extra | 说明 |
|---|---|
| memoria[llm] | LLM 驱动的类型自动分类（OpenAI 兼容接口） |
| memoria[vector] | 向量检索（Qdrant） |
| memoria[local-embed] | 本地向量嵌入（sentence-transformers） |
| memoria[redis] | Redis 存储后端 |
| memoria[postgres] | PostgreSQL 存储后端 |
| memoria[all] | 全部扩展 |

快速开始

import asyncio
from memoria import MemoriaManager
from memoria.config import DictStoreConfig, MemoriaConfig

内存版配置（零依赖起步）；持久化时把 DictStoreConfig 换成 MySQLStoreConfig 等
config = MemoriaConfig(
stores={
"working": DictStoreConfig(max_items=200, ttl_seconds=1800),
"short_term": DictStoreConfig(max_items=5000, ttl_seconds=0),
"long_term": DictStoreConfig(max_items=5000, ttl_seconds=0),
},
indexes={
"working": [],
"short_term": ["keyword", "temporal"],
"long_term": ["keyword", "temporal"],
},
default_layer="short_term",
)

async def main():
manager = MemoriaManager(config)
await manager.initialize()

memory_id = await manager.store(
"用户最喜欢的验证饮料是冷萃铁观音-0827",
types=["semantic"],
importance=0.6,
)

ctx = await manager.contextual_recall("用户最喜欢的验证饮料是什么")
print(ctx.to_prompt())          # 结构化的多管线召回上下文
print(await manager.stats())    # 各层记忆数量与生命周期分布

await manager.close()

asyncio.run(main())

核心概念

五层记忆（sensory → working → short_term → long_term → archive）

- sensory：感知缓冲，短期原始输入
- working：工作记忆，当前任务上下文
- short_term：短期记忆，跨会话近期事实
- long_term：长期记忆，稳定知识与经验
- archive：归档，冷数据（通过 query_archive 检索）

八种记忆类型：episodic（事件）、semantic（事实）、procedural（流程/技能）、relational（关系）、affective（情绪）、spatial（空间）、social（用户画像）、meta（规则/约束）。

五管线上下文召回：contextual_recall() 把召回结果按类型分流成五条管线——reference（参考信息）、profile（用户画像）、skills（技能）、emotion（情绪）、constraints（约束），返回结构化的 MemoryContext，而不是一个扁平列表。

和 Mem0 / AgentMemory 的区别

Mem0、AgentMemory 把记忆当检索问题：向量召回、重排，把结果一股脑塞回上下文。区别只在谁的 embedding 更强、塞多少条。

Memoria 的假设是：记忆的难处不在「搜到」，在「搜到之后」。每条记忆有各自的去向和保质期，混在一起塞给模型是噪声。所以 recall 不返回扁平列表，而是按类型分流成五条管线，各去各的地方。

另一个实际的差别：Memoria 零 LLM 也能跑。默认 keyword（BM25）索引，不接任何模型 API 就能 store / recall，零 token 成本。

现状与 benchmark

LongMemEval-S（500 题）上 Memoria 当前 R@5 = 78.52%（NDCG@5 = 71.18%）。离 Mem0、AgentMemory 等一线框架还有差距，但我们定位到了真正的瓶颈：不在召回（BM25 召回天花板 95%），在召回之后的处理。

完整 benchmark 脚本与实验记录见仓库。

主要 API

| 方法 | 说明 |
|---|---|
| store(content, , types, importance, ...) | 存入一条记忆，返回 memory_id |
| recall(query, , layers, types, ...) | 返回 list[MemoryRecord] |
| contextual_recall(query, *, limit, ...) | 五管线分流召回，返回 MemoryContext |
| forget(memory_id) / remember(memory_id) | 遗忘 / 恢复一条记忆 |
| link(source_id, predicate, target_id) | 建立记忆间关系 |
| stats() | 各层记忆计数与生命周期分布 |

DeepSeek Harness 集成
Memoria 提供 memoria.plugin_server（stdio JSON-RPC 服务），配合 dsh-memoria npm 插件，可作为 DeepSeek Harness 的原生长时记忆插件：每个会话自动注入召回上下文，无需显式调用召回工具。

pip install memoria-framework
dsh plugin --profile web add dsh-memoria

许可证

MIT