Repository navigation
V1 Memory and Knowledge
简体中文 | 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.sequenceInMemorySessionStore 适合测试,JsonlSessionStore 适合受控本地文件,SQLite 适合需要事务、序列检查和完整性链的同机持久化。回放读取历史,不重新请求模型或执行工具;fork 产生有来源序列的独立分支,不改已有事件。用 agent.replay_session()、checkpoint_session()、fork_session() 访问 Agent 层接口。用 ContextProjector 投影消息,用 ContextBudget / ContextCompactor 管理上下文和大工具输出。Session 日志不等于长期记忆,也不替代 持久任务状态。
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 对普通文本和通配符的修正在标签之后合并;不要把它当作此版行为。示例只用固定普通词。
LightAgent Wiki - see the repository, releases, and issues.
- Installation and Your First Agent
- Tools and Integrations
- Memory, Sessions, and RAG
- Workflows and Multiple Agents
- Agent Backends and Codex
- Durable Execution, Jobs, and Subagents
- Safety, Observability, and Evaluation
- Usage, Cost Estimates, and Budgets
- Deployment, Migration, and Verification
- 安装与第一个 Agent
- 工具和集成
- 记忆、会话与 RAG
- 工作流与多 Agent
- 执行后端与 Codex
- 持久执行、Jobs 与 Subagents
- 安全、观测与评测
- 用量统计、费用估算与预算
- 部署、升级与验收
- Quick Start
- Core Concepts
- API Reference
- Examples Cookbook
- Migration Guide
- Tools
- Tool Generator
- Memory
- MCP
- Skills
- LightFlow
- Tree of Thought
- Self-Learning
- Multi-Agent
- Tracing and Debugging
- Langfuse Observability
- Model Providers
- browser-use Integration
- Testing and CI
- Deployment Guide
- Architecture
- Security
- Known Limitations
- FAQ
- FAQ 中文
- Roadmap
- Release Process
- Contributing