记忆模型

XMemo 存储什么

XMemo 保存当前聊天或任务结束后仍然有用的持久上下文：项目事实、决策、偏好、修正和交接备注。临时的对话噪声、一次性回答和原始工具输出不属于 memory。

• semantic — 跨会话仍然成立的持久事实和决策。
• episodic — 发生在任务或会话某个时刻的事件。
• procedural — 在本项目中执行任务的方法。
• working — 当前正在进行的任务的活动状态。
• identity — 关于 owner 或 agent 本身的稳定信息。

写入持久 memory

持久写入需要 content、连接到项目或 namespace 的逻辑 path，以及 memory type。后续 recall 会按 path 进行过滤。

remember({
  content: "Use OAuth for hosted ChatGPT connections.",
  path: "projects/memory-os/decisions"
})

SDK 中的 memory type

MemoryCandidate.memory_type 通过 TypeScript SDK 接受同一组值，因此经过规范化的 agent event 会携带应存储的 type。

import { normalizeAgentEvent, toMemoryCandidate } from '@xmemo/client';

const event = normalizeAgentEvent(
  { type: 'command_completed', command: 'pytest', exit_code: 0, output: '12 passed' },
  { source: 'shell', defaultAgentId: 'codex' },
);

console.log(toMemoryCandidate(event).memory_type); // episodic

交互式来源出处与生命周期演示（合成演示）

分步可验证的生命周期演示，展示记忆创建、跨客户端检索、具有版本更替（v1 -> v2）的实时用户修正、Token 预算保护、软删除墓碑标记以及隔离的合成销毁。每一步均有一次性运行时凭证支持，零暴露真实用户记忆：

• 步骤 1 [STATE_1_CREATED_ACTIVE_V1]：Agent A (Claude Desktop) 通过 tools.py::remember 写入初始偏好，附带不可篡改的作者、实例哈希和设备元数据 — 回执：状态 200 OK，demo_mem_lifecycle_001@v1，active — 状态：[SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 边界：[DEMO_DATA: SYNTHETIC]。
• 步骤 2 [STATE_2_ACCESSED_ATTRIBUTED]：同一授权作用域内的 Agent B (Codex CLI) 立即通过 tools.py::recall 检索记忆，附带引用回执且跨客户端零漂移 — 回执：状态 200 OK，引用 demo_mem_lifecycle_001@v1 — 状态：[SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 边界：[DEMO_DATA: SYNTHETIC]。
• 步骤 3 [STATE_3_CORRECTED_SUPERSEDED_V2]：用户通过 tools.py::update_memory 修正会议室和时间。VersionController 为 v1 创建不可变快照（status='superseded'）并将活动记录升至 v2 — 回执：状态 200 OK，v2，父版本 v1，差异：Room Orion -> Room Polaris — 状态：[SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 边界：[DEMO_DATA: SYNTHETIC]。
• 步骤 4 [STATE_4_RETRIEVAL_FILTERED]：后续 recall 查询仅选择活动 v2，而已废弃的 v1 被严格过滤出 LLM 上下文窗口以防止幻觉并节省 Token 预算 — 回执：状态 200 OK，选择 v2，已排除更替的 v1 — 状态：[SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 边界：[DEMO_DATA: SYNTHETIC]。
• 步骤 5 [STATE_5_TOMBSTONE_DELETED]：所有者通过 tools.py::forget 将事实标记为已删除。它立即从召回候选查询中排除，并移入带恢复操作的回收站视图 — 回执：状态 200 OK，状态：deleted，候选数：0 — 状态：[SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 边界：[DEMO_DATA: SYNTHETIC]。
• 步骤 6 [STATE_6_RESET_PURGED]：隔离的一次性销毁（reset_synthetic_state）将演示作用域记录清除至磁盘上正好 0 个残留行。个人账户硬重置（POST /api/v1/me/memories/reset）被严格排除 — 回执：teardown_status: SUCCESS_PURGED，residual_rows: 0，account_hard_reset_called: FALSE — 状态：[SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — 边界：[DEMO_DATA: SYNTHETIC]。

+------------------------------------------------------------------------------------------------------------------------+
| [PROVENANCE & LIFECYCLE 6-STATE STATE MACHINE: DISPOSABLE HARNESS WALKTHROUGH]                                        |
|                                                                                                                        |
|  Agent A (Claude Desktop)    XMemo FastMCP & Engine           Agent B (Codex CLI)          Demo Owner (Supervising)    |
|  [04f9b8c2 / MacBook]        [VersionController / Scope]      [e81d7a31 / Workstation]     [user:demo_owner]           |
|         |                               |                              |                              |                |
|  (1) remember(sync in Orion)            |                              |                              |                |
|  -------------------------------------> |                              |                              |                |
|         |                          [STATE 1: Created Active v1]        |                              |                |
|  <------------------------------------- |                              |                              |                |
|    Receipt: mem-001@v1                  |                              |                              |                |
|         |                               |      (2) recall(sync)        |                              |                |
|         |                               | <--------------------------- |                              |                |
|         |                               |  [STATE 2: Cited @v1]        |                              |                |
|         |                               | ---------------------------> |                              |                |
|         |                               |   Citation: mem-001@v1       |                              |                |
|         |                               |                              |   (3) update_memory(Polaris) |                |
|         |                               | <---------------------------------------------------------- |                |
|         |                               |                          [STATE 3: Bump v2, Supersede v1]   |                |
|         |                               | ----------------------------------------------------------> |                |
|         |                               |                          Receipt: mem-001@v2 (parent: v1)   |                |
|         |                               |                              |                              |                |
|         |                               |      (4) recall(Polaris)     |                              |                |
|         |                               | <--------------------------- |                              |                |
|         |                               |  [STATE 4: Select v2,        |                              |                |
|         |                               |   Filter superseded v1]      |                              |                |
|         |                               | ---------------------------> |                              |                |
|         |                               |   Citation: mem-001@v2 only  |                              |                |
|         |                               |                              |   (5) forget(mem-001)        |                |
|         |                               | <---------------------------------------------------------- |                |
|         |                               |                          [STATE 5: Tombstone / Trash View]  |                |
|         |                               | ----------------------------------------------------------> |                |
|         |                               |                          Receipt: status=deleted            |                |
|         |                               |                              |                              |                |
|         |                               |   (6) reset_synthetic_state()                               |                |
|         |                               | <---------------------------------------------------------- |                |
|         |                               | [STATE 6: Teardown Purge]                                   |                |
|         |                               | Scope purged: 0 residual rows (account reset excluded)      |                |
|         |                               | ----------------------------------------------------------> |                |
|         |                               | Teardown Status: SUCCESS_PURGED                             |                |
+------------------------------------------------------------------------------------------------------------------------+