llmem-setup

LLMem 设置

安装、配置 LLMem，并将其集成到 Agent 的运行框架中，使其能够使用结构化记忆。

何时运行

• 为新 Agent 设置记忆
• 为现有 Agent 运行框架添加记忆
• 克隆 LLMem 后、首次使用前
• Agent 询问“如何让 llmem 正常运行？”

安装理念

插件优先、零配置说明。 LLMem 使用平台插件，在会话开始时自动注入记忆上下文，在空闲或会话结束时提取记忆，并在上下文压缩期间保留上下文。这意味着：

• 无需手动编辑指令。 插件会处理自动生命周期钩子。
• 技能提供按需行为指导。 Agent 遇到与记忆相关的情况时，会加载相应技能。无需将 80 行指令粘贴到 AGENTS.md 中。
• 在配置中添加一行即可启用所有功能。 添加插件即可完成。

操作步骤

步骤 1：安装 LLMem CLI

# Option A: Install from source (Go binary)
git clone https://github.com/MichielDean/LLMem.git
cd LLMem && make build
# Binary at ~/.local/bin/llmem, symlinked to /usr/local/bin/llmem

# Option B: One-liner
curl -sSL https://raw.githubusercontent.com/MichielDean/LLMem/main/setup.sh | bash

验证：

llmem --help
llmem stats

步骤 2：初始化

llmem init          # Interactive — detects providers
llmem init --non-interactive  # Script-friendly — uses defaults

这会创建 ~/.config/llmem/config.yaml 和 ~/.config/llmem/memory.db。

步骤 3：配置提供方

选择一个：

Ollama（本地，免费）：

curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text
ollama pull qwen2.5:1.5b
# Config auto-detected

OpenAI（云端，需要 API 密钥）：

export OPENAI_API_KEY=sk-...
llmem init --non-interactive

Local（sentence-transformers，无需服务端）：

pip install ".[local]"
# Set provider.default: local in config.yaml

None（仅 FTS5 模式）： 无需任何提供方即可运行。语义搜索已禁用。

步骤 4：安装插件和技能

推荐方式——完全自动：

npm 安装后脚本会部署所有内容：技能、平台插件和工具。

cd LLMem && npm install

这会运行 install.js，该脚本会：

1. 将所有技能目录复制到 ~/.agents/skills/
2. 自动检测你的平台（OpenCode、Claude Code、Copilot CLI）
3. 将正确的插件部署到相应位置
4. 如果检测到 OpenCode，则将 OpenCode 自定义工具部署到 .opencode/tools/

手动部署插件：

如果无法使用 npm install，请手动部署：

平台	插件文件	目标位置
OpenCode	plugins/opencode/llmem.js	~/.config/opencode/plugins/llmem.js
Claude Code	整个 plugins/agent/ 目录	~/.claude/plugins/llmem/
Copilot CLI	整个 plugins/agent/ 目录	~/.copilot/installed-plugins/_direct/llmem/

强制指定平台：

node install.js --platform opencode    # OpenCode only
node install.js --platform claude-code # Claude Code only
node install.js --platform copilot     # Copilot CLI only
node install.js --platform all         # All platforms
node install.js --platform none         # Skills only, no plugins

步骤 5：配置 Agent（按平台）

OpenCode

将插件添加到 opencode.json：

{
  "plugin": ["llmem"]
}

或者，如果使用本地插件部署（文件已由 install.js 复制），则无需配置——OpenCode 会自动发现 ~/.config/opencode/plugins/ 中的插件。

在 LLMem 仓库中工作时，OpenCode 会自动发现自定义工具（.opencode/tools/）。对于其他项目，请复制 .opencode/tools/ 目录，或通过 OPENCODE_CONFIG_DIR 引用该目录。

AGENTS.md 中的说明——可选。 插件会在会话开始时注入上下文。llmem 技能会按需加载。如果希望添加持久提醒，可添加以下最简一行：

## Memory

Plugin-managed. Search when uncertain: `llmem search "topic"`. Add when you learn: `llmem add --type fact --content "..."`.

Claude Code

插件安装在 ~/.claude/plugins/llmem/。启用插件：

claude plugin install ~/.claude/plugins/llmem
# Or use --plugin-dir for testing:
claude --plugin-dir ~/.claude/plugins/llmem

插件提供：

• SessionStart 钩子：在会话开始时注入 llmem stats 和 llmem search
• PreCompact 钩子：在上下文压缩前注入关键记忆
• 技能：llmem、llmem-setup——按需加载

CLAUDE.md 中的说明——可选。 SessionStart 钩子会注入上下文。如果希望添加持久提醒：

## Memory

Plugin-managed. Search when uncertain: `llmem search "topic"`. Add when you learn: `llmem add --type fact --content "..."`.

Copilot CLI

插件安装在 ~/.copilot/installed-plugins/_direct/llmem/。启用插件：

copilot plugin install ~/.copilot/installed-plugins/_direct/llmem
# Or install directly from the GitHub repo:
copilot plugin install MichielDean/LLMem:plugins/agent

Copilot CLI 使用与 Claude Code 相同的插件格式（.claude-plugin/plugin.json），但安装到 ~/.copilot/ 而不是 ~/.claude/。钩子和技能完全相同。

COPILOT.md 中的说明——可选。 如果希望添加持久提醒：

## Memory

Plugin-managed. Search when uncertain: `llmem search "topic"`. Add when you learn: `llmem add --type fact --content "..."`.

步骤 6：验证

# CLI works
llmem --help
llmem stats

# Can add and search
llmem add --type fact --content "test memory"
llmem search "test"

# Skills are discoverable
ls ~/.agents/skills/llmem

# Plugin deployed
# OpenCode:
ls ~/.config/opencode/plugins/llmem.js
# Claude Code:
ls ~/.claude/plugins/llmem/.claude-plugin/plugin.json
# Copilot CLI:
ls ~/.copilot/installed-plugins/_direct/llmem/.claude-plugin/plugin.json

# Optional: verify OpenCode tools
ls .opencode/tools/llmem-*.ts

步骤 7：Dream Timer（可选）

用于自动整合记忆：

# Copy and enable systemd timer
cp harness/llmem-dream.service ~/.config/systemd/user/
cp harness/llmem-dream.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable llmem-dream.timer
systemctl --user start llmem-dream.timer

默认在每晚凌晨 3 点运行。可在 ~/.config/llmem/config.yaml 的 dream: 下进行配置。

架构

Agent Session
    │
    ├── Plugin (auto, no instructions needed)
    │   ├── session.created/start → llmem stats + llmem search → inject context
    │   └── session.compacting    → llmem search → preserve key memories
    │
    ├── Skills (on-demand, loaded by trigger)
    │   ├── llmem                      → CLI reference, memory types, commands
    │   └── llmem-setup                → This file
    │
    └── Custom Tools (structural, zero-instruction)
        ├── llmem-search   → Search memories
        ├── llmem-add      → Add a memory
        ├── llmem-context  → Get context for a topic
        ├── llmem-invalidate → Soft-delete a memory
        └── llmem-stats    → Show memory statistics

插件负责处理 Agent 在物理上无法自行完成的所有事项（在第一条消息发送前注入上下文，在压缩期间保留关键记忆）。当 Agent 需要行为指导时，技能会提供相应指导。自定义工具提供对记忆操作的类型化访问，无需加载技能。

故障排除

llmem: command not found —— 二进制文件不在 PATH 中。检查 which llmem 或 ls ~/.local/bin/llmem。可能需要运行 ln -s ~/.local/bin/llmem /usr/local/bin/llmem。

Ollama not reachable —— 启动 Ollama（ollama serve）、拉取模型（ollama pull nomic-embed-text），或切换提供商。LLMem 会依次回退：Ollama → OpenAI → Anthropic → 本地 → 无（仅 FTS5）。

插件未加载 —— 确认插件文件存在于预期路径。对于 OpenCode，检查 ~/.config/opencode/plugins/llmem.js。对于 Claude Code，检查 ~/.claude/plugins/llmem/。

未发现技能 —— 确认技能目录：ls ~/.agents/skills/llmem/。如果目录不存在，请重新运行 node install.js。

会话开始时未注入上下文 —— 检查插件日志。对于 OpenCode，手动运行 llmem stats，确认命令可以正常工作。插件运行的就是这些相同的命令。