Memory & Workspace¶

Agentica 提供两层记忆系统：运行时记忆（WorkingMemory） 和 持久化记忆（Workspace）。

运行时记忆：WorkingMemory¶

管理当前会话的消息历史，支持 token 感知的截断。

from agentica import Agent

agent = Agent(
    add_history_to_messages=True,   # 将历史加入上下文
    history_window=5,               # 保留最近 5 轮
)

会话摘要¶

WorkingMemory 支持自动生成会话摘要，在多轮对话后保留关键信息：

from agentica.memory import WorkingMemory

agent = Agent(
    working_memory=WorkingMemory(
        create_session_summary=True,            # 每轮结束后生成摘要
        update_session_summary_after_run=True,  # 自动更新
        max_messages=200,                       # 消息软上限（FIFO 淘汰）
    ),
)

会话摘要会注入到 System Prompt 末尾，同时被 CompressionManager.auto_compact() 直接复用——压缩时无需额外 LLM 调用。

持久化记忆：Workspace¶

基于文件的持久化记忆，存储跨会话的用户偏好、项目上下文和反馈记录：

workspace/
+-- AGENTS.md         # Agent 全局指令（共享）
+-- PERSONA.md       # Agent 人格设定（共享）
+-- TOOLS.md         # 工具使用说明（共享）
+-- users/
    +-- {user_id}/   # 多用户隔离
        +-- USER.md          # 用户个人信息
        +-- MEMORY.md        # 记忆索引（仅存条目链接，≤200行/25KB）
        +-- memory/          # 记忆内容文件（每条独立 .md）
            +-- feedback_python_style.md
            +-- project_deadline.md
            +-- user_background.md
        +-- conversations/   # 对话归档
            +-- 2026-04-01.md

基本用法¶

from agentica import Agent, Workspace

agent = Agent(
    workspace=Workspace(path="./my_workspace", user_id="alice"),
)

记忆写入：write_memory_entry()¶

推荐使用 write_memory_entry() 写入带类型的记忆条目。每条记忆写入独立文件，并自动更新 MEMORY.md 索引。

workspace = Workspace("./workspace")
workspace.initialize()

# 写入用户偏好
await workspace.write_memory_entry(
    title="Python Style",
    content="User prefers concise, typed Python. Avoid unnecessary comments.",
    memory_type="feedback",           # user | feedback | project | reference
    description="python coding style typed concise",  # 相关性匹配关键词
    sync_to_global_agent_md=True,     # 可选：同步到 ~/.agentica/AGENTS.md
)

# 写入项目上下文
await workspace.write_memory_entry(
    title="Release Deadline",
    content="v2.0 release is due end of April 2026.",
    memory_type="project",
    description="v2 release deadline april 2026",
)

每条记忆文件带 YAML frontmatter：

---
name: Python Style
description: python coding style typed concise
type: feedback
---

User prefers concise, typed Python. Avoid unnecessary comments.

四类型分类法¶

类型	存储内容	典型触发
`user`	用户角色、偏好、技术背景	"我是数据科学家"、"我用 Python 10 年了"
`feedback`	对 AI 行为的纠正和确认	"别 mock 数据库"、"这个方案很好"
`project`	非代码可推导的项目上下文	"合并冻结从周四开始"、"这是合规要求"
`reference`	外部系统指针	"pipeline bugs 在 Linear INGEST 项目"

feedback 类型同时记录失败（"不要这样做"）和成功（"对，就这样"）——只记录纠错会导致 AI 行为随时间漂移。

全局偏好同步：`~/.agentica/AGENTS.md`¶

learn-from-experience 这类学习型 workflow 的一个关键优点，是把“已经确认、值得长期保留的偏好”编译进每个新 session 都会加载的全局 steering 文件。Agentica 现在也支持这条轻量链路。

同步方式有两层：

单次写入时显式同步：

await workspace.write_memory_entry(
    title="Python Style",
    content="Prefer concise, typed Python. Avoid unnecessary getattr.",
    memory_type="feedback",
    description="python style concise typed",
    sync_to_global_agent_md=True,
)

Agent 运行时默认开启同步：

from agentica import DeepAgent, Workspace
from agentica.agent.config import WorkspaceMemoryConfig

agent = DeepAgent(
    workspace=Workspace("./workspace"),
    long_term_memory_config=WorkspaceMemoryConfig(
        sync_memories_to_global_agent_md=True,
    ),
)

行为说明： - 只同步 user 和 feedback 类型 - 同步目标是 ~/.agentica/AGENTS.md 的 ## Learned Preferences 区块 - 这个区块是编译产物，应编辑原始 memory entry，而不是直接改同步块 - Workspace.get_context_prompt() 会自动加载全局 AGENTS.md，所以下一个 session 会自然继承这些偏好

这不是完整的 HOT/WARM/COLD 分层系统，而是一个更轻量、对现有框架更友好的落地方式。

记忆召回：get_relevant_memories()¶

记忆注入采用相关性召回，而非全量 dump。

# 根据当前 query 返回最相关的 ≤5 条记忆
memory = await workspace.get_relevant_memories(
    query="how should I write python code",
    limit=5,
    already_surfaced=set(),   # 去重：本 session 已展示过的文件名
)

召回机制： 1. 解析 MEMORY.md 索引，获取所有条目的 title + description hook 2. 用 混合关键词 scoring（word-level + character 2-gram）对每条打分，支持中英文 3. 只加载 top-k 个文件内容，拼接后注入 system prompt 4. 自动 strip frontmatter，追加 drift-defense 提示

MEMORY.md 的大小有硬限制（200 行 / 25KB），超出时 FIFO 淘汰最旧条目，防止无限增长。

Agent 自动召回¶

Agent 使用 workspace 时，每次 run() 会自动以当前 query 为输入执行记忆召回：

from agentica import Agent, Workspace
from agentica.agent.config import WorkspaceMemoryConfig

agent = Agent(
    workspace=Workspace("./workspace"),
    long_term_memory_config=WorkspaceMemoryConfig(
        load_workspace_memory=True,
        max_memory_entries=5,   # 最多注入 5 条相关记忆
    ),
)

_surfaced_memories 跨 turn 追踪已展示的记忆文件，避免同一 session 内重复注入相同条目。

记忆漂移防御¶

记忆注入时自动追加一条提示，防止过时引用造成幻觉：

Note: memories reflect the state at write time. If a memory references a specific
file path, function, or flag, verify it still exists before recommending it.

Git 上下文注入¶

Workspace 支持自动注入 Git 状态到 System Prompt：

agent = Agent(
    workspace=Workspace(path="./my_project"),
)
# System Prompt 将包含：
# - Git branch: main
# - Uncommitted changes: M file1.py, A file2.py
# - Recent commits: abc1234 feat: add new feature

Workspace.get_git_context() 获取分支名、未提交变更、最近 3 条 commit。

对话归档¶

使用 ConversationArchiveHooks 自动将对话归档到每日日志文件：

from agentica import Agent, Workspace
from agentica.agent.config import WorkspaceMemoryConfig

agent = Agent(
    workspace=Workspace("./workspace"),
    long_term_memory_config=WorkspaceMemoryConfig(auto_archive=True),
)

归档写入 users/{user_id}/conversations/YYYY-MM-DD.md，使用 per-file asyncio.Lock 防止并发写冲突。

Session Log（JSONL）¶

基于追加写 JSONL 的会话日志，支持会话恢复和 fork：

from agentica import Agent

agent = Agent(session_id="my-session-001")
# 消息自动写入 .sessions/my-session-001.jsonl
# 下次以相同 session_id 创建 Agent 时自动恢复会话

支持 compact_boundary（压缩边界）：恢复时从最后一个边界之后开始加载，跳过历史数据。

WorkspaceConfig¶

可自定义文件布局：

from agentica.workspace import Workspace, WorkspaceConfig

config = WorkspaceConfig(
    agent_md="AGENTS.md",
    persona_md="PERSONA.md",
    tools_md="TOOLS.md",
    user_md="USER.md",
    memory_md="MEMORY.md",      # 记忆索引文件
    memory_dir="memory",         # 记忆内容文件目录
    users_dir="users",
    conversations_dir="conversations",
)

workspace = Workspace(path="./workspace", config=config)

下一步¶

Agent 核心概念 — Agent 如何使用记忆
Hooks — ConversationArchiveHooks 详解
Context Compression — 上下文压缩与会话摘要复用