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

License

MIT