Memory API

列出记忆条目

GET /api/memory?type=semantic&page=1&page_size=20&sort_by=created_at&sort_order=desc&tag=python

参数	类型	默认值	说明
`type`	string	全部	记忆类型过滤: `semantic`, `episodic`, `procedural`, `conversation`, `task_digest`
`page`	int	1	页码（从 1 开始）
`page_size`	int	20	每页条数（最大 100）
`sort_by`	string	`created_at`	排序字段: `created_at`, `updated_at`, `importance`
`sort_order`	string	`desc`	排序方向: `asc` 或 `desc`
`tag`	string	—	按标签过滤（不区分大小写）
`search`	string	—	语义搜索查询（使用向量相似度）

响应：

{
  "items": [...],
  "total": 91,
  "page": 1,
  "page_size": 20,
  "has_next": true,
  "has_prev": false
}

获取记忆标签

GET /api/memory/tags?limit=20

返回所有记忆类型中最常用的标签及其计数。

搜索记忆

GET /api/v1/memory/search?query=user%20preferences%20for%20coding%20style&memory_types=semantic,episodic&limit=10

参数	类型	默认值	说明
`query`	string	—	搜索查询（必填，使用向量相似度）
`memory_types`	string	全部	以逗号分隔的记忆类型，例如 `semantic,episodic`
`limit`	int	10	最大返回条数（1-50）
`session_id`	string	—	可选会话 ID；排序信号按该会话的偏好调整

响应：

{
  "results": [...],
  "scores": [0.91, 0.84],
  "query": "user preferences for coding style",
  "total": 2
}

results 与 scores 按下标一一对应。

创建记忆条目

POST /api/memory

{
  "type": "semantic",
  "content": "User prefers TypeScript with strict mode",
  "importance": 0.8
}

删除记忆条目

DELETE /api/memory/:id

记忆指挥中心

获取完整的记忆系统健康状态和诊断快照，用于设置页面展示。Memory Labs 为实验功能，默认关闭（服务端 MYRM_MEMORY_LABS，WebUI NEXT_PUBLIC_MEMORY_LABS=1），/memory/command-center* 路由仅在开启后挂载，但 GET /memory/command-center/graph 与 GET /memory/command-center/evidence/playback 例外：默认的成长页知识图谱标签页和记忆证据抽屉依赖它们，所以始终挂载。

GET /api/v1/memory/command-center?project_id=<可选>

参数	类型	默认值	说明
`project_id`	string	—	可选的项目 ID，用于将快照范围限定为单个项目的记忆空间

响应包含：概览统计、记忆空间、治理项、健康诊断、时间线事件、迁移状态、运行时配置等。提供 project_id 时，spaces、governance 和 timeline 部分仅显示与该项目 SharedContext 绑定相关的数据。空字符串会被自动归一化为全局视图。

学习演化时间线 API

记忆与技能生命周期融合时序流与行内即时治理接口。

获取统一学习演化时间线

GET /api/v1/statistics/learning-timeline?days=30&limit=50&kind_filter=fact_memory,skill_evolution&cursor=2026-10-01T08:00:00+00:00|mem_123

参数	类型	默认值	说明
`days`	int	30	回溯天数（1-365）
`agent_id`	string	—	仅保留该智能体的节点（无智能体归属的节点始终保留）
`kind_filter`	string	全部	逗号分隔的节点类型：`fact_memory`、`preference_memory`、`procedural_memory`、`episodic_memory`、`skill_evolution`、`skill_draft`
`limit`	int	50	单页数量（1-100）
`cursor`	string	—	上一页返回的不透明 `next_cursor`

响应示例：

{
  "items": [
    {
      "id": "mem_123",
      "kind": "fact_memory",
      "title": "Factual Knowledge",
      "content": "用户偏好使用严格的 TypeScript 类型检查与纯函数",
      "created_at": "2026-10-01T08:00:00+00:00",
      "importance": 0.9,
      "confidence": 0.95,
      "is_user_protected": false,
      "metadata": { "memory_type": "semantic" }
    }
  ],
  "has_more": true,
  "next_cursor": "2026-10-01T08:00:00+00:00|mem_123",
  "total_count": 42
}

total_count 为满足全部过滤条件的节点总数（每个来源最多取最新 500 条）。技能节点携带 metadata.manageable、metadata.archived、metadata.pinned。cursor 或 kind_filter 非法时返回 400。 is_user_protected 表示用户已保护该记忆（已固定，或被锁定的程序性规则）；source_chat_id 是记忆被提取时所在的对话；程序性规则没有重要度评分，其 importance 仅为占位值。

更新时间线记忆规则

PUT /api/v1/statistics/learning-timeline/memory/:memory_type/:id

:memory_type 取节点的 metadata.memory_type（semantic、episodic 或 procedural）。

{
  "content": "修改后的规则正文",
  "importance": 0.9,
  "reasoning": "用户在时间线编辑器中显式纠错"
}

importance 为可选项，仅在传入时生效。编辑会保护该记忆：程序性规则被锁定，语义/情景记忆被固定，自动遗忘、合并与改写都会跳过它们；记忆条目以 is_user_locked: true 表示这一保护状态。记忆不存在返回 404，内容被拒绝返回 400。

删除时间线记忆条目

DELETE /api/v1/statistics/learning-timeline/memory/:id?memory_type=semantic

语义与情景记忆为软删除（进入记忆回收站，可通过 POST /api/v1/memory/trash/:id/restore 恢复）；程序性规则为永久删除。

归档 / 恢复技能

POST /api/v1/statistics/learning-timeline/skill/:skill_name/archive?active=false

active=false 归档技能，active=true 恢复。已固定的技能返回 409，技能不存在返回 404。

{
  "skill_name": "code-reviewer",
  "is_active": false,
  "message": "Skill archived"
}

记忆指挥中心：长程记忆经济学剖析

仅在开启 Memory Labs 后可用。

GET /api/v1/memory/command-center/economics?conversation_id=conv-xxx&window=50

参数	类型	默认值	说明
`conversation_id`	string	`None`	会话标识符过滤（留空则统计全局有状态长程轨迹）
`window`	int	50	统计近 N 轮时序轨迹窗口大小（最大 200）

响应：

{
  "kpis": {
    "total_injected_turns": 42,
    "avg_load_ratio": 0.18,
    "avg_phase_latency_ms": {
      "retrieval": 12.4,
      "assembly": 4.1,
      "injection": 1.8
    },
    "long_horizon_roi": "optimal"
  },
  "turn_trajectories": [
    {
      "turn": 1,
      "retrieval_ms": 14.2,
      "assembly_ms": 3.8,
      "injection_ms": 1.5,
      "load_ratio": 0.12,
      "injected_tokens": 320
    }
  ],
  "parasitic_stale_items": [
    {
      "id": "mem-123",
      "content": "陈旧未被引用的历史死胡同规约",
      "created_at": "2026-06-01T00:00:00Z",
      "access_count": 0,
      "estimated_tokens": 150
    }
  ]
}

​Memory API

​列出记忆条目

​获取记忆标签

​搜索记忆

​创建记忆条目

​删除记忆条目

​记忆指挥中心

​学习演化时间线 API

​获取统一学习演化时间线

​更新时间线记忆规则

​删除时间线记忆条目

​归档 / 恢复技能

​记忆指挥中心：长程记忆经济学剖析