llmem

LLMem

LLMem 是一个结构化记忆系统（Go 二进制程序）。它使用 SQLite 存储事实记忆，并可选通过 Ollama（nomic-embed-text）进行基于嵌入的语义搜索。语义搜索使用 sqlite-vec HNSW ANN 索引实现亚线性检索；如果 sqlite-vec 扩展不可用，则会自动回退到暴力余弦相似度计算。记忆之间可以通过类型化关系（related_to、supersedes、contradicts、depends_on、derived_from）建立联系。后台梦境整理系统（浅层、深层、REM 阶段）通过 systemd 定时器自动运行，用于衰减闲置记忆、提升频繁访问的记忆、晋升高价值记忆，以及合并近似重复的记忆。

安装

• CLI： ~/.local/bin/llmem
• 配置： ~/.config/llmem/config.yaml
• 数据库： ~/.config/llmem/memory.db
• Ollama： http://localhost:11434（本地，用于嵌入）

会话适配器配置

LLMem 使用会话适配器读取对话记录，以提取记忆。在 config.yaml 中设置 session.adapter：

• opencode（默认）— 从 ~/.local/share/opencode/opencode.db 读取。如果数据库存在，则自动选用。
• copilot — 从 ~/.copilot/session-state/ 读取。如果仅存在 Copilot 会话数据，则自动选用。完整记录需要 --share。
• none — 不使用适配器。上下文注入仍可正常工作，但记录提取会返回 no_transcript。

# For Copilot CLI:
session:
  adapter: copilot
copilot:
  state_dir: ~/.copilot/session-state
  share_dir: .

llmem init 会根据存在的会话状态目录自动检测适配器类型。

记忆类型

类型	用途
fact	客观事实、定义、世界状态
decision	已做出的选择及其理由
preference	用户偏好、风格选择
event	在某个时间点发生的事情
project_state	项目或系统的当前状态
procedure	操作知识、步骤序列
conversation	值得注意的对话结果或承诺

主要命令

# Add a memory
llmem add --content "content" --type fact
llmem add --content "prefer dark theme" --type preference --confidence 0.9

# Search memories (hybrid RRF fusion by default)
llmem search "query"
llmem search "query" --type decision --limit 5
llmem search "query" --fts-only        # FTS5 keyword search only (no embedder needed)
llmem search "query" --semantic-only   # Semantic (embedding) search only (requires embedder)
llmem search "query" --valid-only     # Only show valid (non-expired) memories

# List all
llmem list
llmem list --type fact --limit 20
llmem list --all                       # Include expired memories

# Get specific memory (read-only, does not update access stats)
llmem get <id>

# Update a memory
llmem update <id> --content "new content"
llmem update <id> --confidence 0.95
llmem update <id> --summary "short summary"
llmem update <id> --metadata '{"key": "value"}'

# Invalidate (soft-delete — marks as expired)
llmem invalidate <id> --reason "no longer relevant"

# Delete permanently
llmem delete <id>

# Stats
llmem stats

# Dream — background consolidation (decay, boost, promote, merge)
llmem dream                                               # Preview all phases (dry-run)
llmem dream --apply                                       # Execute all phases
llmem dream --phase light                                 # Run only the light phase
llmem dream --phase deep                                  # Run only the deep phase
llmem dream --phase rem                                   # Run only the REM phase
llmem dream --apply --phase deep                          # Apply only the deep phase
llmem dream --apply --report /path/to/report.html         # Generate HTML dream report

# Export/import
llmem export --output memories.json
llmem import memories.json

# Embedding quality metrics
llmem metrics

# Initialize config and database
llmem init
llmem init --ollama-url http://localhost:11434

关系

记忆之间可以通过类型化关系建立联系：supersedes、contradicts、depends_on、related_to、derived_from。

关系由梦境系统和提取流程在内部管理。Go 后端支持在搜索中遍历关系（通过 Retriever API 提供），但 CLI 尚未提供 --traverse-relations 标志。

多信号重排序

RRF 融合后，搜索结果会自动重排序，综合 RRF 分数和四种加权信号：

final_score = rrf_score * (1 - blend) + weighted_signal * blend

默认混合系数：0.3（70% RRF，30% 信号）。

信号及权重：

信号	权重	公式
置信度	0.4	直接使用 confidence 字段（0.0–1.0，默认值为 0.0）
时效性	0.3	exp(-0.01 * days_since_access)（从未访问时为 0.0）
访问频率	0.2	log(1 + access_count / max(age_days, 1))（从未访问时为 0.0）
类型优先级	0.1	在 TYPE_PRIORITY 字典中查找（未知类型默认值为 1.0）

类型优先级权重：

类型	优先级
decision	1.2
preference	1.1
procedure	1.1
fact	1.0
project_state	1.0
event	0.9
conversation	0.7

重要说明

• Go 二进制文件 — llmem 现在是编译后的 Go 二进制文件，位于 ~/.local/bin/llmem，并通过符号链接连接到 /usr/local/bin/llmem。无需 Python 虚拟环境。
• 失效，而非删除，除非记忆有误。失效的记忆仍会保留以供参考，但不会在搜索结果中返回。
• 嵌入需要 Ollama 正在运行，并已拉取 nomic-embed-text。如果 Ollama 未运行，语义搜索会退回到仅使用 FTS5。
• ANN 向量索引 — 语义搜索使用 sqlite-vec（vec0 虚拟表）进行快速 ANN 检索；如果 sqlite-vec 不可用，则会自动退回到暴力余弦相似度计算。
• 置信度范围为 0.0-1.0。数值越高，表示越确定。直接来自用户的事实应为 0.9 以上，自动提取的内容应为 0.7。
• 上下文生成使用 llmem search <query> 查找相关记忆，以注入会话。插件会在会话开始时自动处理此操作。
• 访问跟踪 — llmem get 为只读操作，不会更新 access_count 或 accessed_at。搜索操作会自动跟踪访问情况 — 每条返回结果的 access_count 和 accessed_at 都会更新（尽力而为）。

梦境 — 后台整合

梦境系统是一条自动化记忆维护流水线，分为三个阶段：

• 轻度 — 使用余弦相似度查找近似重复项（阈值可配置，默认为 0.92）。生成合并候选项，供深度阶段处理。
• 深度 — 衰减闲置记忆（置信度随时间降低）、提升频繁访问的记忆、晋升高分记忆，并使用 LLM 辅助合并近似重复项；如果失败，则退回到拼接方式。
• REM — 从记忆中提取主题和聚类，将人类可读的梦境日记写入 ~/.config/llmem/dream-diary.md。生成类型计数、词语聚类以及记忆总数和活跃记忆数。

默认模式为试运行 — 使用 --apply 实际应用更改。不加该参数时，llmem dream 只会预览将要执行的操作。使用 --report /path/to/report.html 生成 HTML 梦境报告。

计划任务：systemd 用户计时器（llmem-dream.timer）会在每天凌晨 3 点运行 llmem dream --apply。参见 harness/llmem-dream.service 和 harness/llmem-dream.timer。

梦境配置位于 ~/.config/llmem/config.yaml 中的 dream: 键下：

键	默认值	描述
similarity_threshold	0.92	用于检测近似重复项的余弦相似度
decay_rate	0.05	每个衰减周期降低的置信度
decay_interval_days	30	每个衰减周期的天数
decay_floor	0.3	衰减后的最低置信度
confidence_floor	0.3	置信度小于或等于此值的记忆会被设为失效
boost_threshold	5	触发置信度提升的访问次数
boost_amount	0.05	置信度提升幅度
diary_path	~/.config/llmem/dream-diary.md	梦境日记文件的路径
report_path	(无)	HTML 梦境报告的输出路径
auto_link_threshold	(无)	自动关联相关记忆的余弦相似度阈值