目录

Mnemon — 记忆导入指南

在 GitHub 上查看源文件

本文档说明如何将历史聊天记录或外部上下文批量导入 Mnemon 的记忆图谱。


工作流概览

聊天导出 / Markdown -> LLM 提取提示词 -> memory_draft.json -> mnemon import <file>
  1. 将原始聊天记录或笔记导出为 Markdown 或纯文本。
  2. 将文本连同下方的参考提示词一起发送给 LLM,生成符合本文档格式的 memory_draft.json。
  3. 运行 mnemon import memory_draft.json,Mnemon 自动完成去重、图谱边构建、 可用时的向量嵌入和生命周期评分。

导入文件格式(schema_version: "1")

json
{
  "schema_version": "1",
  "source": "chat-export",
  "insights": [
    {
      "content": "选择了 Qdrant 而非 Milvus 作为向量搜索引擎,主要原因是其过滤查询性能更好。",
      "category": "decision",
      "importance": 5,
      "tags": ["architecture", "search", "vector-db"],
      "entities": ["Qdrant", "Milvus"],
      "source": "agent",
      "created_at": "2024-03-15T09:30:00Z"
    },
    {
      "content": "用户偏好简洁的 API 响应,不希望看到多余的解释文本。",
      "category": "preference",
      "importance": 4,
      "tags": ["ux", "api"]
    }
  ],
  "edges": [
    {
      "source_index": 0,
      "target_index": 1,
      "edge_type": "causal",
      "weight": 0.7,
      "reason": "向量引擎选型决策影响了 API 响应设计偏好"
    }
  ]
}

字段说明

顶层字段

字段 类型 必填 说明
schema_version string 是 必须为 "1"
source string 否 整批导入的来源标签,如 "chat-export"、"manual"。单条 insight 可通过自身的 source 覆盖此值
insights array 是 记忆节点列表,至少包含一项
edges array 否 显式关系列表;Mnemon 的图引擎也会自动创建边,此处用于补充已知的强关联

insights 条目字段

字段 类型 必填 约束 说明
content string 是 最多 8000 字符 记忆文本
category string 否 见下表,默认 general 知识类型
importance integer 否 1-5,默认 3 重要程度;影响保留优先级和排序
tags array 否 最多 20 项,每项最多 100 字符 用于检索和过滤的自由标签
entities array 否 最多 50 项,每项最多 200 字符 记忆中涉及的命名主体,如人名、项目名、工具、库或组织;会与 Mnemon 自动提取结果合并
source string 否 - 覆盖顶层 source,表示该条记忆的具体来源
created_at string 否 RFC 3339 格式 原始创建时间;省略时使用导入时间

category 可选值

值 适用场景
preference 用户偏好、习惯、风格要求
decision 已确定的技术或产品决策
fact 客观事实、数据、限制、规格参数
insight 推断、分析结论、经验总结
context 项目背景、状态、约束条件
general 其他不适合上述分类的记忆

importance 赋值建议

值 含义
5 核心决策或强烈偏好,应长期保留
4 重要上下文,通常需要保留
3 一般记忆,默认值
2 次要细节,后续可能被剪枝
1 临时或低价值信息

edges 条目字段

字段 类型 必填 约束 说明
source_index integer 是 insights 数组的零基索引 边的起点
target_index integer 是 不能等于 source_index 边的终点
edge_type string 是 见下表 关系类型
weight float 否 0.0-1.0,默认 0.5 关系强度
reason string 否 - 说明该关系存在的原因,会作为边元数据保存

edge_type 可选值

值 含义
temporal 时间顺序关系,事件 A 发生在事件 B 之前
causal 因果关系,A 导致或影响 B
semantic 语义相似关系,A 与 B 讨论同一主题
entity 实体共现关系,A 与 B 涉及同一命名主体
supersedes 权威声明:A 取代 B,召回时 B 被降权

使用命令

bash
# 基本导入
mnemon import memory_draft.json

# 验证格式但不写入数据库
mnemon import --dry-run memory_draft.json

# 跳过去重检测,将所有条目作为新记忆插入
mnemon import --no-diff memory_draft.json

# 指定具体 store
mnemon import --store project-alpha memory_draft.json

输出示例

导入与 remember 使用相同的精确内容去重规则:仅跳过与活跃记忆逐字节 完全相同的内容。不同事实、近似重复、冲突和变化后的属性值都会新增。 被跳过的草稿索引映射到已有 insight ID,显式边仍可引用该记忆。 如需淘汰已被取代的事实,请验证新记忆后显式执行 mnemon forget <old-id>。 基于容量的自动清理仍独立生效。

json
{
  "imported": 8,
  "updated": 0,
  "skipped": 2,
  "errors": 0,
  "edges_inserted": 3,
  "auto_pruned": 0,
  "auto_pruned_ids": [],
  "results": [
    {"index": 0, "id": "a1b2c3d4...", "content": "选择了 Qdrant...", "action": "added"},
    {"index": 1, "id": "e5f6a7b8...", "content": "用户偏好简洁的...", "action": "skipped"}
  ]
}
字段 说明
imported 新增的记忆数量
updated 固定为 0,保留此字段以兼容已有输出;相似度不会触发替换
skipped 因内容逐字节完全相同而跳过的数量
errors 写入失败的数量;导入允许部分成功,脚本调用方应检查此字段是否为 0
edges_inserted 成功插入的显式边数量
auto_pruned 超出容量限制后自动删除的记忆数量
auto_pruned_ids 被自动软删除的准确 ID;每个 ID 都有对应的 prune oplog 记录

参考提示词(用于生成 memory_draft.json)

将以下提示词和你的聊天记录一起发送给 LLM:

text
你是一个记忆提取助手。请从下方的聊天记录或文档中提取有价值的长期知识片段,
生成一个符合 Mnemon memory draft 格式(schema_version: "1")的 JSON 文件。

## 提取规则

1. 每条 insight 必须是独立、完整的知识单元,不依赖原始上下文即可理解。
2. 去除闲聊、重复表述和无长期价值的内容。
3. 如果同一主题多次出现,合并为一条最完整的表述,不要重复。
4. 按以下优先级分配 importance:
   - 5:关键架构决策、明确的用户核心偏好
   - 4:重要上下文、反复出现的模式
   - 3:一般事实和背景信息
   - 2:细节或一次性提及的内容
   - 1:临时状态或极低价值信息
5. entities 填写记忆中出现的具体名词:人名、项目名、工具/库名、组织名、
   API、服务或产品名。
6. tags 使用小写英文,用连字符分隔词语,如 "vector-db"、"api-design"。
7. 如果能从上下文推断出原始时间,在 created_at 中填写 RFC 3339 格式时间。
8. edges 只填写显而易见的强关联关系,不要过度连接。

## 输出要求

- 只输出 JSON,不要有任何解释文字。
- 严格遵守以下 schema:

{
  "schema_version": "1",
  "source": "chat-export",
  "insights": [
    {
      "content": "...",
      "category": "preference|decision|fact|insight|context|general",
      "importance": 1-5,
      "tags": ["tag1", "tag2"],
      "entities": ["Entity1", "Entity2"],
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "edges": [
    {
      "source_index": 0,
      "target_index": 1,
      "edge_type": "causal|semantic|temporal|entity",
      "weight": 0.0-1.0,
      "reason": "..."
    }
  ]
}

## 待处理内容

[在此粘贴你的聊天记录或文档]

常见问题

Q: created_at 必须填吗?
不必须。省略时 Mnemon 使用导入时间。如果原始聊天记录有时间戳,建议填写以保留历史顺序。

Q: 导入后如何验证结果?
运行 mnemon log、mnemon status 或 mnemon search <关键词> 确认导入结果。

Q: edges 数组必须填吗?
不必须。Mnemon 会自动创建时序、语义和实体边。显式 edges 用于指定 LLM 能明确判断的强关联关系。

Q: 如何分批导入大型聊天记录?
将聊天记录按时间段或主题切分为多个文件,依次执行 mnemon import。重复内容会被内置 diff 自动跳过,除非使用 --no-diff。

Q: 可以导入非英文内容吗?
可以,content、tags、entities 均支持 Unicode 文本。