企业官网建设流程全解析

Semantica 跨会话记忆完整教程：如何让 AI Agent 重启后接着干

【免费下载链接】semanticaGraph-Native Infrastructure for Context and Accountable AI Systems项目地址: https://gitcode.com/GitHub_Trending/sema/semantica

Semantica 的跨会话记忆解决 AI Agent 的一个通病：进程一结束，对话历史、积累的发现、做过的决策全部清零，下次启动等于重头再来。它把"Agent 学到的一切"写进磁盘，AgentContext 负责编排整个存取过程，下次开机一条load()全量恢复，不用重新读源文档、也不用重新向量化。本文从一个值班交接的场景出发，带你走通初始化、存取、存档读档的完整链路。

值班交接场景：为什么"重启就失忆"很痛 🕹️

这一节先讲清楚要解决什么问题：Agent 在两个进程之间如何不丢上下文。

想象一个安全分析 Agent：白天处理了一串告警，内存里积累了"IP — 域名 — 攻击活动"的完整关联。18 点进程退出，夜班 Agent 启动，用户问"那个 C2 域名关联到哪个活动"——新进程一无所知，因为数据只活在上一进程的内存里。传统 RAG 的解法是每次查询重新读文件、重新 embedding，慢，而且两次运行的结果不一定一致。Semantica 的思路是"一次写入、长期召回"：store()在学习发生的那一刻付一次成本，之后的每个会话都直接查落盘状态。这套机制分散在 AgentMemory 记忆管理 和 VectorStore 向量存储 等文件中，但你对外的入口只有一个。

五行代码初始化：记忆系统的三个部件 📦

这一节解决"记忆到底由什么组成、怎么把它建起来"的问题。

Semantica 的记忆不是一个对象，而是三个部件协同：AgentContext是你操作的入口，内部同时驱动——

• AgentMemory：短期缓冲，默认缓存最近 10 条 / 2000 token，超了自动淘汰最旧条目；
• VectorStore：长期记忆，把文字变成向量，按语义相似度检索，不依赖关键词精确匹配；
• ContextGraph：结构记忆，用图存实体和关系，支持多跳遍历，能找到纯向量搜索"够不着"的关联。

可以把它们类比成大脑里的草稿纸（缓冲）、档案柜（向量）和卡片目录（图）：

from semantica.context import AgentContext, ContextGraph from semantica.vector_store import VectorStore agent = AgentContext( vector_store=VectorStore(backend="faiss", dimension=768), knowledge_graph=ContextGraph(), retention_days=365, # 记忆保留天数 max_memories=50000, # 环形缓冲区上限 )

用 store 和 retrieve 存取记忆 ✍️

这一节演示最日常的用法：一句话写入，按语义召回。

agent.store("用户偏好：报告用中文，图表用蓝色系", metadata={"type": "preference"}, conversation_id="user_1024") hits = agent.retrieve("用户的语言偏好", max_results=3) for h in hits: print(h["score"], h["content"])

注意conversation_id这个参数，它是命名空间：不同任务打不同 ID，检索时按 ID 过滤，记忆互不串扰。如果传入的是一份文档列表，store()还能顺带抽取实体与关系写入图，为后续图增强检索打基础。

存档与读档：save() 与 load() 落盘了什么 💾

这一节拆解跨会话记忆的核心机制——三份状态怎么落盘、怎么还原。

进程退出前调一次save(path)，它同时写三份状态：

agent_state/ ├── agent_memory.json # 记忆条目 + 元数据 ├── vector_store/ # 向量索引（FAISS index.bin 等） └── knowledge_graph.json # 实体与关系图

新进程启动时，用相同配置（同 backend、同 dimension）重建 context，再一行还原：

agent.save("agent_state/") # 退出前存档 # —— 新进程 —— agent.load("agent_state/") # 读档，记忆与图关系立即可用

一个关键细节：load()是覆盖而非合并——它会清掉当前内存、图和向量状态再载入，所以读档前请确认当前状态已保存，或直接使用全新 context。这套存档/读档机制也天然支持多 Agent 交接：A 进程save()，B 进程甚至 B 台机器load()，无缝接棒，多 Agent 指南里有完整的交接示例。

调一调检索手感：四个值得调的参数 ⚖️

这一节解决"存取得到，但检索效果怎么调"的问题。先看速查表：

三条实战建议：新导入语料、图还很稀疏时，hybrid_alpha从接近 0 起步（更信语义相似度），图厚起来再上调；长任务在关键步骤用checkpoint("步骤名")打命名快照，再用diff_checkpoints()对比两个阶段之间新增了哪些决策和关系，方便复盘；需要审计的场景开启decision_tracking=True，决策会连同推理路径存进图。官方指南对每个参数都有更细的说明。

翻车自查表：记忆为什么"没了" 🧯

这一节帮你快速定位最常见的四类问题：

TL;DR：store()积累 +save()存档 +load()读档，把这三步嵌进 Agent 生命周期，重启就是"接着干"。

【免费下载链接】semanticaGraph-Native Infrastructure for Context and Accountable AI Systems项目地址: https://gitcode.com/GitHub_Trending/sema/semantica