Agent Memory 与 Context Engineering：从任务状态到长期记忆治理

1
订单 ORD-A1B2C3D4 三天没发货，我以后都希望优先短信通知。

1
Conversation History
2
  保存原始话语与时间
3

4
AgentState
5
  order_id=ORD-A1B2C3D4, intent=refund_or_logistics
6

7
Business Fact
8
  是否三天未发货必须查询订单/物流系统验证
9

10
Long-term Profile Memory
11
  notification_preference=sms（需确认、作用域和可删除）
12

13
Context
14
  当前节点只加载必要字段，不一定加载整段原话

1
聊天记录 == 记忆           错：原始历史未经筛选、冲突与隐私治理
2
向量库 == 记忆系统         错：它只是索引/召回的一种实现
3
上下文窗口变大 == 不需记忆 错：成本、注意力、权限与新鲜度仍需管理

1
目标
2
槽位
3
最新工具事实引用
4
待验证假设
5
已完成步骤
6
待执行动作
7
预算

1
2026-07-10 用户因订单 X 的物流延误联系过客服，最终转人工处理。

1
用户偏好短信通知
2
商家 A 属于跨境业务
3
“妥投”表示物流已签收

1
处理退款时先查订单和物流，再查生效规则，最后验证动作结果。

1
{
2
  "entity": "user:123",
3
  "notification_preference": "sms",
4
  "language": "zh-CN",
5
  "preferred_contact_hours": "09:00-18:00 Asia/Shanghai"
6
}

1
已确认事实
2
未决问题
3
关键决定及证据引用
4
承诺与截止时间
5
不确定项
6
源消息范围
7
摘要版本

1
Vector：语义近邻召回
2
Graph：实体、事件、事实、时间与关系遍历

1
Canonical Memory Store
2
  保存完整记录、版本、来源、时间、ACL、删除状态
3

4
Vector / Search / Graph Index
5
  可重建的读取投影
6

7
Context Cache
8
  短期加速结果，带 TTL 与版本

1
from datetime import datetime
2
from typing import Literal
3
from pydantic import BaseModel, Field
4

5

6
class MemoryRecord(BaseModel):
7
    memory_id: str
8
    schema_version: Literal["2"] = "2"
9
    tenant_id: str
10
    namespace: str
11
    subject_ref: str
12
    kind: Literal[
13
        "episodic",
14
        "semantic",
15
        "profile",
16
        "procedural",
17
        "summary",
18
    ]
19
    key: str | None
20
    content: str
21
    structured_value: dict | None
22
    source_refs: list[str]
23
    source_type: Literal[
24
        "user_assertion",
25
        "verified_tool_fact",
26
        "human_review",
27
        "derived_summary",
28
        "system_policy",
29
    ]
30
    confidence: float = Field(ge=0, le=1)
31
    sensitivity: Literal["public", "internal", "confidential", "restricted"]
32
    valid_from: datetime | None
33
    valid_to: datetime | None
34
    recorded_at: datetime
35
    expires_at: datetime | None
36
    consent_ref: str | None
37
    status: Literal["active", "superseded", "invalidated", "deleted"]
38
    version: int

1
Valid Time
2
  这条事实在现实世界何时成立？
3

4
Transaction/Recorded Time
5
  系统何时知道并记录它？

1
2026-07-01 用户偏好 Email 生效
2
2026-07-05 系统才收到并记录
3
2026-07-10 用户改为 SMS

1
谁说的？
2
来自哪个消息/工具/文档？
3
是否经过验证？
4
用哪个提取器/Prompt/模型生成？
5
基于哪些源范围做摘要？
6
后来被什么记录覆盖或撤回？

1
tenant/{tenant_id}
2
tenant/{tenant_id}/user/{user_id}
3
tenant/{tenant_id}/team/{team_id}
4
tenant/{tenant_id}/project/{project_id}
5
tenant/{tenant_id}/agent/{agent_id}
6
tenant/{tenant_id}/thread/{thread_id}

1
Identity -> Allowed Namespaces -> Memory Type -> Time -> Retrieval

1
谁可写
2
谁可读
3
谁可批准
4
冲突如何处理
5
哪些 Agent 产出只能是候选
6
是否允许从私有作用域提升到共享作用域

1
profile.notification_preference
2
profile.language
3
profile.timezone

1
Observe Event
2
  -> Candidate Extraction
3
  -> Normalize
4
  -> Sensitivity Detection
5
  -> Consent / Retention Check
6
  -> Source Validation
7
  -> Duplicate Retrieval
8
  -> Conflict Resolution
9
  -> Mutation Proposal
10
  -> Policy Decision
11
  -> Transactional Commit
12
  -> Index Update
13
  -> Audit / Eval Sample

1
class MemoryMutationProposal(BaseModel):
2
    operation: Literal["add", "update", "invalidate", "delete", "no_op"]
3
    namespace: str
4
    kind: str
5
    key: str | None
6
    candidate_content: str | None
7
    source_refs: list[str]
8
    matched_memory_ids: list[str]
9
    conflict_type: str | None
10
    confidence: float
11
    reason_code: str

1
Hot Path
2
  用户当前回复依赖立即写入
3
  优点：一致性直观
4
  缺点：增加延迟，失败影响主链路
5

6
Background
7
  事件进入队列，异步提取/去重/提交
8
  优点：可批处理、可用更强模型
9
  缺点：最终一致、需要 watermark 与重放

1
last_event_seen
2
last_event_committed
3
last_index_updated

1
NEW          没有相关旧记录
2
DUPLICATE    语义相同，无需新增
3
REFINEMENT   新记录更精确，更新/合并
4
SUPERSEDES   新事实替代旧事实
5
CONFLICTS    来源或时间无法自动判定

1
M1: 用户偏好 Email，来源=user assertion，valid_from=07-01
2
M2: 用户偏好 SMS，来源=user assertion，valid_from=07-10

1
human verified
2
> authenticated user explicit statement
3
> verified business tool
4
> derived summary
5
> model inference

1
UPDATE memory_records
2
SET structured_value = :value,
3
    source_refs = :sources,
4
    version = version + 1,
5
    recorded_at = now()
6
WHERE memory_id = :id
7
  AND version = :expected_version;

1
Canonical Transaction
2
  1. insert/update memory_record
3
  2. append memory_outbox event
4
  3. commit
5

6
Index Worker
7
  4. consume outbox idempotently
8
  5. update vector/search/graph projections
9
  6. record projection watermark
10
  7. mark event processed

1
CREATE TABLE memory_records (
2
  memory_id text NOT NULL,
3
  tenant_id text NOT NULL,
4
  namespace text NOT NULL,
5
  kind text NOT NULL,
6
  content text NOT NULL,
7
  source_refs jsonb NOT NULL,
8
  valid_from timestamptz,
9
  valid_to timestamptz,
10
  status text NOT NULL,
11
  version integer NOT NULL,
12
  recorded_at timestamptz NOT NULL,
13
  PRIMARY KEY (memory_id, version)
14
);
15

16
CREATE TABLE memory_outbox (
17
  event_id text PRIMARY KEY,
18
  memory_id text NOT NULL,
19
  memory_version integer NOT NULL,
20
  operation text NOT NULL,
21
  payload jsonb NOT NULL,
22
  created_at timestamptz NOT NULL,
23
  processed_at timestamptz
24
);

1
扫描未处理 Outbox
2
比较 Canonical 与 Index version/hash
3
重建缺失向量或图边
4
移除已 tombstone 的投影
5
刷新失效 Cache
6
记录 repair reason 与结果

1
memory_outbox_lag_seconds
2
memory_projection_version_lag
3
memory_index_repair_total{reason,status}
4
memory_canonical_index_mismatch_total

1
Task + Current State
2
  -> Query Intent
3
  -> Namespace/ACL Filter
4
  -> Memory Type Filter
5
  -> Valid-time/Expiry Filter
6
  -> Candidate Retrieval
7
  -> Trust/Freshness Rerank
8
  -> Deduplicate/Conflict Group
9
  -> Diversity Selection
10
  -> Context Budget Allocation
11
  -> Context Items + Provenance

1
score =
2
  semantic_relevance
3
  + task_relevance
4
  + source_trust
5
  + freshness
6
  + explicit_user_priority
7
  - conflict_penalty
8
  - staleness_penalty
9
  - redundancy_penalty
10
  - privacy_risk

1
class RetrievedMemory(BaseModel):
2
    memory_id: str
3
    version: int
4
    kind: str
5
    content: str
6
    source_refs: list[str]
7
    valid_from: datetime | None
8
    confidence: float
9
    retrieval_score: float
10
    retrieval_reasons: list[str]
11
    conflict_group: str | None

1
没有找到已确认偏好
2
找到两条相互冲突的当前偏好
3
只有低置信推断，不应自动使用
4
记忆已过期，需要重新确认

1
System / Policy Instructions
2
Current Goal
3
Typed AgentState
4
Verified Tool Facts
5
Retrieved Business Evidence
6
Relevant Conversation Slice
7
Selected Memory
8
Available Tool Schemas
9
Output Contract
10
Reserved Generation Budget

1
class ContextBudget(BaseModel):
2
    total_tokens: int
3
    reserved_output_tokens: int
4
    instructions_tokens: int
5
    state_tokens: int
6
    tool_schema_tokens: int
7
    evidence_tokens: int
8
    conversation_tokens: int
9
    memory_tokens: int

1
class ContextItem(BaseModel):
2
    item_id: str
3
    kind: str
4
    content: str
5
    trust: Literal["instruction", "verified", "untrusted"]
6
    source_refs: list[str]
7
    token_estimate: int
8
    priority: int
9
    expires_at: datetime | None

1
任务目标
2
已验证事实及引用
3
关键决策
4
未完成步骤
5
外部操作 ID
6
用户确认范围
7
预算与错误状态
8
原消息范围引用

1
结构化事实
2
+ content hash
3
+ source reference
4
+ truncated/omitted indicator

1
数据持久化位置
2
session/thread key 语义
3
多租户隔离
4
并发写入
5
删除/保留
6
消息裁剪/摘要
7
是否自动注入
8
可否导出与迁移

1
current node
2
completed steps
3
pending action
4
tool operation IDs
5
budget
6
pinned versions

1
不同租户同名用户冲突
2
团队/项目作用域丢失
3
删除无法定位派生记录
4
测试环境污染生产画像

1
Profile
2
  当前值紧凑、读取简单、更新有冲突
3

4
Collection
5
  多条记忆保留历史、检索灵活、需要聚合

1
Memory Poisoning
2
Persistent Prompt Injection
3
Cross-tenant Retrieval
4
Sensitive Inference
5
Secret Memorization
6
Unauthorized Promotion to Shared Scope
7
Deletion Failure
8
Stale Policy/Preference

1
PII/Secret classification
2
consent and purpose check
3
namespace authorization
4
source trust
5
injection markers
6
retention policy
7
minimum necessary content

1
authenticated identity
2
tenant + resource ACL
3
purpose limitation
4
sensitivity ceiling
5
valid time + expiry
6
untrusted-content labeling

1
Delete Request
2
  -> Resolve subject/source scope
3
  -> Tombstone canonical records
4
  -> Remove vector/search/graph indexes
5
  -> Invalidate caches/context snapshots
6
  -> Propagate to derived summaries
7
  -> Schedule backup expiry where applicable
8
  -> Emit deletion evidence
9
  -> Verify no active read path returns record

1
{
2
  "deletion_id": "del_01J...",
3
  "subject_ref": "tenant/a/user/123",
4
  "requested_at": "2026-07-15T10:00:00Z",
5
  "canonical_records": 12,
6
  "indexes_removed": ["vector", "search", "graph"],
7
  "derived_records_invalidated": 3,
8
  "cache_namespaces_invalidated": 2,
9
  "verification_status": "passed",
10
  "backup_retention_deadline": "2026-08-14T10:00:00Z"
11
}

1
{
2
  "run_id": "run_01J...",
3
  "intent": "refund_request",
4
  "order_id": "ORD-A1B2C3D4",
5
  "verified_fact_refs": [
6
    "order://ORD-A1B2C3D4?version=8",
7
    "logistics://ORD-A1B2C3D4?version=3"
8
  ],
9
  "policy_refs": ["policy://refund/v18#R001"],
10
  "pending_action": "refund:create",
11
  "status": "awaiting_confirmation"
12
}

1
{
2
  "kind": "episodic",
3
  "subject_ref": "order:ORD-A1B2C3D4",
4
  "content": "用户因超过72小时未发货申请退款，规则R001命中，确认后退款完成",
5
  "source_refs": [
6
    "run://run_01J...",
7
    "refund://RF-20260715-88"
8
  ],
9
  "valid_from": "2026-07-15T09:20:00Z",
10
  "expires_at": "2026-10-15T00:00:00Z"
11
}

1
{
2
  "kind": "profile",
3
  "namespace": "tenant/shop-a/user/123",
4
  "key": "notification.preference",
5
  "structured_value": {
6
    "channel": "sms",
7
    "quiet_hours": "22:00-08:00 Asia/Shanghai"
8
  },
9
  "source_type": "user_assertion",
10
  "consent_ref": "consent://memory/2026-07-15/7",
11
  "confidence": 1.0,
12
  "status": "active"
13
}

1
User: 以后物流更新请优先短信通知
2
-> Extract candidate: notification.preference=sms
3
-> Verify explicit user statement
4
-> Sensitivity: low, purpose: service personalization
5
-> Consent policy: allowed + visible/editable
6
-> Retrieve current profile value
7
-> Conflict: email -> sms, explicit newer statement
8
-> CAS update canonical profile
9
-> Update indexes/cache
10
-> Show confirmation and memory control link

1
New logistics task
2
-> Identity -> tenant/user namespace
3
-> Query relevant profile keys
4
-> Check valid/expiry/consent
5
-> Context Builder selects sms preference
6
-> Tool policy verifies SMS channel is available
7
-> Action still requires normal authorization

1
User: 忘掉我的通知偏好
2
-> Resolve profile key and derived summaries
3
-> Tombstone canonical value
4
-> Invalidate cache/index
5
-> Verify retrieval returns no active preference
6
-> Return delete receipt

1
Candidate Extraction Precision/Recall
2
Write Decision Accuracy
3
Sensitive Write Block Rate
4
Duplicate Rate
5
Conflict Detection Recall
6
Mutation Accuracy
7
Provenance Completeness
8
Write Latency / Cost

1
Memory Recall@K
2
Memory Precision@K
3
Required Memory Recall
4
Stale Memory Rate
5
Conflict Surfacing Rate
6
Unauthorized Retrieval Rate
7
Source Citation Accuracy
8
Tokens per Useful Memory

1
Task Success with Memory
2
Task Success without Memory
3
Wrong Personalization Rate
4
Clarification Reduction
5
Repeated Work Reduction
6
Latency / Cost Delta
7
User Correction Rate
8
Delete Compliance

1
A: no memory
2
B: oracle memory
3
C: production retrieval
4
D: stale/conflicting memory injected
5
E: unauthorized memory must be blocked

1
系统是否需要记忆
2
写入是否正确
3
检索是否正确
4
模型是否正确使用
5
错误记忆是否会伤害任务

1
{
2
  "case_id": "M-PREF-013",
3
  "history_events": [
4
    "event://user-preference-email",
5
    "event://user-preference-sms-later"
6
  ],
7
  "current_task": "通知物流异常",
8
  "expected_active_memory": {
9
    "key": "notification.preference",
10
    "value": "sms"
11
  },
12
  "expected_invalidated_memory_ids": ["mem_email_v1"],
13
  "forbidden_namespaces": ["tenant/other/user/123"],
14
  "expected_action": "send_sms_after_policy_check"
15
}

1
用户更正
2
用户删除
3
模型忽略/采用某条记忆
4
工具动作成功或失败
5
人工审核
6
投诉与满意度

1
class MemoryFeedbackEvent(BaseModel):
2
    event_id: str
3
    memory_id: str
4
    memory_version: int
5
    run_id: str
6
    feedback_type: Literal[
7
        "used",
8
        "ignored",
9
        "corrected",
10
        "confirmed",
11
        "harmful",
12
        "deleted",
13
    ]
14
    source: Literal["user", "human_reviewer", "verifier", "system_metric"]
15
    evidence_refs: list[str]
16
    occurred_at: datetime

1
Write Accepted / Rejected / Deferred Rate
2
Canonical Commit Latency
3
Index Freshness Lag
4
Retrieval p50/p95
5
Context Memory Token Share
6
Stale/Conflict/Unauthorized Retrieval Rate
7
Memory-caused Task Failure Rate
8
Correction and Deletion Completion Time
9
Cost per Memory-assisted Successful Run

1
明确偏好
2
否定句
3
临时偏好
4
第三方信息
5
敏感推断
6
Secret
7
间接 Prompt Injection
8
用户撤回
9
同一字段并发更新

1
新事实晚记录但早生效
2
两个来源同一时间冲突
3
摘要遗漏否定词
4
旧事实过期但索引仍命中
5
Add 成功、Index 失败
6
Index 成功、Canonical Transaction 回滚

1
跨租户近邻更相似
2
namespace filter 缺失
3
低置信记忆排名过高
4
同义重复占满 top-k
5
冲突只返回一侧
6
恶意记忆试图改变系统指令

1
Canonical tombstone 后 vector cache 仍返回
2
Graph edge 未级联失效
3
Derived summary 仍含被删事实
4
并发 Run 持有旧 Context Package
5
备份保留期未披露