Skip to content

V1 Memory and Knowledge

weego edited this page Nov 15, 2026 · 2 revisions

记忆、会话与 RAG

简体中文 | English

适用版本:v1.0.0。这三种状态解决不同问题,不应该互相代替。

需求 接口 保存什么
记住用户明确授权的长期偏好 MemoryProtocol、MemoryPolicy 按用户、租户、来源、范围划分的记忆。
恢复一次对话或复盘模型/工具操作 Session、SqliteSessionStore 有序事件、回合、checkpoint 和分叉。
查找有出处的事实材料 SqliteFTSRetrievalProvider 文档与切片、来源、citation ID;检索不等于模型事实验证。

长期记忆与隔离

适配器实现 store(data, user_id) 和 retrieve(query, user_id);可选 metadata 参数能保存来源和范围。返回结果形如 {"results": [...]}。以下用内存实现验证基本隔离,无需模型或数据库:

from LightAgent import SharedMemoryPool

pool = SharedMemoryPool(agent_name="guide")
pool.store("Alice prefers concise summaries.", user_id="tenant-a:alice")
pool.store("Bob prefers detailed summaries.", user_id="tenant-b:bob")

alice = pool.list_records(user_id="tenant-a:alice")
assert len(alice) == 1
assert pool.list_records(user_id="tenant-c:alice") == []
print(pool.retrieve("concise", user_id="tenant-a:alice")["results"])

接入 Agent 时使用 memory=pool,更换后端时保留协议。由业务端从登录身份推导命名空间和 user_id,不要信任调用方随意给出的租户标识。共享内存原型仅在当前进程保存数据,生产持久化需外部后端;可选 Mem0 用 mem0 extra。可参考 Mem0 示例、向量适配示例、MemCode 和 ClawMem。

生产应用应明确配置 MemoryPolicy:读取限制来源、范围和归属,可拒绝无来源记录;写入限制重复、数量、低质量内容,设置 require_write_admission=True 时必须显式准入。这段示例只允许限定长度的用户范围记忆,生产应用可以追加基于可信审核记录的判定:

from LightAgent import MemoryPolicy

def admit_user_preference(data, context):
    return context["source"] == "user" and context["scope"] == "user" and len(data) <= 200

policy = MemoryPolicy(
    namespace="tenant-a",
    allow_unattributed_results=False,
    allowed_sources=("user",),
    allowed_scopes=("user",),
    require_write_admission=True,
    memory_write_admission=admit_user_preference,
    max_writes_per_run=1,
)

自我学习反思或内部证据默认形成不可注入的 MemoryCandidate。用 agent.list_memory_candidates() 审查,必要时通过可信宿主调用 agent.promote_memory_candidate(candidate_id, decision=...),或配置 memory_promotion_admission,结合 MemoryPromotionDecision 与晋升 Hooks 记录允许、拒绝、改写或保留。不要把低信任内容通过晋升直接变成系统指令。应用负责保留时长、删除和后端权限;框架测试不能证明任意真实图数据库的底层事务或隔离正确。详见 写入准入、记忆安全 和 记忆与委托边界。

会话、回放与分支

在 Agent 构造时传 session_store=SqliteSessionStore(...),在多轮运行时传入同一业务会话的 session_id。用户身份和会话归属应在应用层校验,不能把知道 session ID 当成授权。低层离线示例:

from pathlib import Path
from tempfile import TemporaryDirectory

from LightAgent import Session, SqliteSessionStore

with TemporaryDirectory() as directory:
    store = SqliteSessionStore(Path(directory) / "sessions.sqlite3")
    session = store.create(Session(session_id="guide"))
    session.append("message.received", {"content": "保留这条项目决策。"})
    saved = session.checkpoint("before-review")
    store.save(session)
    restored = store.get("guide")
    print(restored.replay().to_dict())
    assert restored.replay().last_sequence >= saved.sequence

InMemorySessionStore 适合测试,JsonlSessionStore 适合受控本地文件,SQLite 适合需要事务、序列检查和完整性链的同机持久化。回放读取历史,不重新请求模型或执行工具;fork 产生有来源序列的独立分支,不改已有事件。用 agent.replay_session()、checkpoint_session()、fork_session() 访问 Agent 层接口。用 ContextProjector 投影消息,用 ContextBudget / ContextCompactor 管理上下文和大工具输出。Session 日志不等于长期记忆,也不替代 持久任务状态。

SQLite 知识检索

from pathlib import Path
from tempfile import TemporaryDirectory

from LightAgent import RetrievalDocument, SqliteFTSRetrievalProvider

with TemporaryDirectory() as directory:
    rag = SqliteFTSRetrievalProvider(Path(directory) / "knowledge.sqlite3")
    rag.ingest(RetrievalDocument(
        document_id="manual",
        title="验收说明",
        source="handbook.md",
        tenant_id="acme",
        content="Run regression tests before release.",
    ))
    matches = rag.search("regression", tenant_id="acme", limit=3)
    assert matches and not rag.search("regression", tenant_id="other")
    for match in matches:
        print(match.citation_id, match.source, match.content)

使用 read_chunk() 回看引用,使用 list_documents()、remove()、reindex() 管理本地索引。检索要传来自授权上下文的 scope、owner、tenant 限制,且下游仍需检查引用权限。SessionSearchProvider 查的是 Session 事件,返回 session:<id>:<sequence> 引用,不是知识库。版本区别: v1.0.0 标签的 provider 仍使用原来的 FTS5/LIKE 查询语义,PR #124 对普通文本和通配符的修正在标签之后合并;不要把它当作此版行为。示例只用固定普通词。

Clone this wiki locally