记忆系统

Agent 的长期记忆存储，支持跨会话知识积累。2026-04-26 后，记忆系统从“对话开始静默预取”调整为“Prompt 强约束 + Agent 显式调用工具”，并补齐了管理页面、类型管理、MySQL/SQLite 双后端分页和统计能力。

关键文件

文件	职责
`memory/provider.ts`	记忆提供商接口定义
`memory/factory.ts`	工厂函数（MySQL/SQLite 切换）
`memory/registry.ts`	按 Agent 缓存 MemoryProvider，统一路由 MySQL/SQLite
`memory/mysql_provider.ts`	MySQL 实现
`memory/sqlite_provider.ts`	SQLite 实现（本地轻量，含迁移、FTS、busy_timeout）
`service/memory_admin.ts`	管理端记忆分页、增删改查、统计
`service/memory_type.ts`	记忆类型 CRUD 和系统类型删除保护
`tools/builtin/memory.ts`	`memory_save` / `memory_recall` 工具
`tools/builtin/memory_types.ts`	`memory_list_types` / `memory_stats` 工具
`views/memory.vue`	前端记忆管理页

提供商接口

interface MemoryProvider {
  save(entry): Promise<MemoryEntry>;
  update(id, partial): Promise<MemoryEntry>;
  delete(id): Promise<void>;
  search(query, opts): Promise<MemoryEntry[]>;
  list(opts): Promise<MemoryEntry[]>;
  getById(id): Promise<MemoryEntry | null>;
  page(opts): Promise<MemoryPageResult>;
  count(opts): Promise<number>;
}

page 和 count 是管理页与统计侧的关键接口；userId 在管理查询里可选，以支持跨用户检索。tool-governance 在解析工具时会根据 Agent 的 memory 配置注入记忆工具。

记忆类型

类型	用途	说明
`user`	用户画像和偏好	系统内置类型
`project`	项目知识和进展	系统内置类型
`feedback`	用户纠正/确认	系统内置类型
`reference`	外部资源链接	系统内置类型
自定义类型	业务扩展	存储在 `netaclaw_memory_type`

netaclaw_memory_type 使用 key/name/description/icon/isSystem 描述类型。系统内置类型不可删除；Agent 可通过 memory_list_types 查看当前可用类型。

工作流

Agent 执行前
  → AgentExecutor 检查 memory.enabled
  → MemoryProviderRegistry 按 Agent 选择 MySQL/SQLite provider
  → provider.count() 只判断是否已有记忆，不静默读取内容
  → prompt_builder 在 Layer 1.5 注入记忆行为指令
  → tool_resolver 强制注入 memory_save / memory_recall / memory_list_types / memory_stats
  → Agent 必须显式调用 memory_recall 后再使用或更新记忆

这条路径的设计目标是避免旧的静默 prefetch 把过期或不相关记忆塞进上下文。Prompt 会要求已有记忆时先 memory_recall，需要全量回忆时使用 query="*"，环境类记忆写入前要先检索，避免多设备/路径信息重复写入。

工具语义

工具	作用	关键约束
`memory_save`	create/update/delete 记忆	create 时同 agent/user/type/name 已存在则幂等更新
`memory_recall`	按 query/type/id 检索	query 为空或 `*` 时走 list；search 失败时 fallback list
`memory_list_types`	列出可用类型	优先读 DB 类型，失败回落内置类型
`memory_stats`	统计当前 Agent 记忆数量和类型分布	基于 provider.list

数据表

netaclaw_memory：

agentName（索引）、userId（索引）
type（user/project/feedback/reference/自定义）
name（标题）、content（正文）、description
metadata（结构化元数据）

netaclaw_memory_type：

key（唯一类型标识）
name、description、icon
isSystem（系统类型删除保护）

管理页

/agent/memory 提供记忆管理 UI：

左侧按 Agent 展示统计，并标识 MySQL/SQLite 后端。
右侧支持按 Agent、类型、关键词分页筛选。
支持新增、编辑、删除记忆；编辑时使用 updatedAt 做乐观锁。
类型管理弹窗可新增/删除自定义类型，系统类型不可删除。

管理 API 在 /admin/netaclaw/memory/* 和 /admin/netaclaw/memory_type/* 下，跨后端查询时 MySQL 直接分页，SQLite Agent 通过 provider 聚合后排序分页。

5.0 KiB Raw Blame History Unescape Escape

记忆系统

关键文件

提供商接口

记忆类型

工作流

工具语义

数据表

管理页

相关页面

5.0 KiB

Raw Blame History