mnemon

LLM 代理的持久内存 CLI。存储事实、回忆过去的知识、链接相关记忆、管理生命周期。

# mnemon

## Install & Configure

### 1. Install the binary

**Homebrew** (macOS / Linux):

```bash
brew install mnemon-dev/tap/mnemon
```

**Go install**:

```bash
go install github.com/mnemon-dev/mnemon@latest
```

### 2. Set up OpenClaw integration

```bash
mnemon setup --target openclaw --yes
```

This single command deploys all components:
- **Skill** → `~/.openclaw/skills/mnemon/SKILL.md`
- **Hook** → `~/.openclaw/hooks/mnemon-prime/` (agent:bootstrap — injects behavioral guide)
- **Plugin** → `~/.openclaw/extensions/mnemon/` (remind, nudge, compact hooks)
- **Prompts** → `~/.mnemon/prompt/` (guide.md, skill.md)

Restart the OpenClaw gateway to activate.

### 3. Customize (optional)

Edit `~/.mnemon/prompt/guide.md` to tune recall/remember behavior.

Plugin hooks are configured in `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "mnemon": {
        "enabled": true,
        "config": {
          "remind": true,
          "nudge": true,
          "compact": false
        }
      }
    }
  }
}
```

| Hook | Default | Description |
|------|---------|-------------|
| `remind` | on | Recall relevant memories + remind agent on each message |
| `nudge` | on | Suggest remember sub-agent after each reply |
| `compact` | off | Save key insights before context compaction |

### 4. Uninstall

```bash
mnemon setup --eject --target openclaw --yes
```

## Workflow

1. **Remember**: `mnemon remember "<fact>" --cat <cat> --imp <1-5> --entities "e1,e2" --source agent`
   - Diff is built-in: duplicates skipped, conflicts auto-replaced.
   - Output includes `action` (added/updated/skipped), `semantic_candidates`, `causal_candidates`.
2. **Link** (evaluate candidates from step 1 — use judgment, not mechanical rules):
   - Review `causal_candidates`: does a genuine cause-effect relationship exist? `causal_signal` is regex-based and prone to false positives — only link if the memories are truly causally related.
   - Review `semantic_candidates`: are these memories meaningfully related? High `similarity` alone is not sufficient — skip candidates that share keywords but discuss unrelated topics.
   - Syntax: `mnemon link <id> <candidate> --type <causal|semantic> --weight <0-1> [--meta '<json>']`
3. **Recall**: `mnemon recall "<query>" --limit 10`

## Commands

```bash
mnemon remember "<fact>" --cat <cat> --imp <1-5> --entities "e1,e2" --source agent
mnemon link <id1> <id2> --type <type> --weight <0-1> [--meta '<json>']
mnemon recall "<query>" --limit 10
mnemon search "<query>" --limit 10
mnemon forget <id>
mnemon related <id> --edge causal
mnemon gc --threshold 0.4
mnemon gc --keep <id>
mnemon status
mnemon log
mnemon store list
mnemon store create <name>
mnemon store set <name>
mnemon store remove <name>
```

## Guardrails

- Use the `exec` tool to run mnemon commands.
- Do not store secrets, passwords, or tokens.
- Categories: `preference` · `decision` · `insight` · `fact` · `context`
- Edge types: `temporal` · `semantic` · `causal` · `entity`
- Max 8,000 chars per insight.

---

## 中文说明

# mnemon

## 安装与配置

### 1. 安装二进制文件

**Homebrew**（macOS / Linux）：

```bash
brew install mnemon-dev/tap/mnemon
```

**Go 安装**：

```bash
go install github.com/mnemon-dev/mnemon@latest
```

### 2. 设置 OpenClaw 集成

```bash
mnemon setup --target openclaw --yes
```

这一条命令即可部署所有组件：
- **Skill** → `~/.openclaw/skills/mnemon/SKILL.md`
- **Hook** → `~/.openclaw/hooks/mnemon-prime/`（agent:bootstrap —— 注入行为指南）
- **Plugin** → `~/.openclaw/extensions/mnemon/`（remind、nudge、compact 钩子）
- **Prompts** → `~/.mnemon/prompt/`（guide.md、skill.md）

重启 OpenClaw 网关以激活。

### 3. 自定义（可选）

编辑 `~/.mnemon/prompt/guide.md` 以调整 recall/remember 行为。

插件钩子在 `~/.openclaw/openclaw.json` 中配置：

```json
{
  "plugins": {
    "entries": {
      "mnemon": {
        "enabled": true,
        "config": {
          "remind": true,
          "nudge": true,
          "compact": false
        }
      }
    }
  }
}
```

| 钩子 | 默认值 | 说明 |
|------|---------|-------------|
| `remind` | 开启 | 在每条消息上回忆相关记忆并提醒代理 |
| `nudge` | 开启 | 每次回复后建议调用 remember 子代理 |
| `compact` | 关闭 | 在上下文压缩前保存关键洞见 |

### 4. 卸载

```bash
mnemon setup --eject --target openclaw --yes
```

## 工作流

1. **Remember（记住）**：`mnemon remember "<fact>" --cat <cat> --imp <1-5> --entities "e1,e2" --source agent`
   - 内置 diff：跳过重复项，自动替换冲突项。
   - 输出包含 `action`（added/updated/skipped）、`semantic_candidates`、`causal_candidates`。
2. **Link（链接）**（评估步骤 1 中的候选项 —— 使用判断力，而非机械规则）：
   - 审查 `causal_candidates`：是否存在真正的因果关系？`causal_signal` 基于正则表达式，容易产生误报 —— 只有当记忆确实存在因果关联时才进行链接。
   - 审查 `semantic_candidates`：这些记忆是否有实质性关联？仅有高 `similarity` 是不够的 —— 跳过那些共享关键词但讨论不相关主题的候选项。
   - 语法：`mnemon link <id> <candidate> --type <causal|semantic> --weight <0-1> [--meta '<json>']`
3. **Recall（回忆）**：`mnemon recall "<query>" --limit 10`

## 命令

```bash
mnemon remember "<fact>" --cat <cat> --imp <1-5> --entities "e1,e2" --source agent
mnemon link <id1> <id2> --type <type> --weight <0-1> [--meta '<json>']
mnemon recall "<query>" --limit 10
mnemon search "<query>" --limit 10
mnemon forget <id>
mnemon related <id> --edge causal
mnemon gc --threshold 0.4
mnemon gc --keep <id>
mnemon status
mnemon log
mnemon store list
mnemon store create <name>
mnemon store set <name>
mnemon store remove <name>
```

## 防护准则

- 使用 `exec` 工具运行 mnemon 命令。
- 不要存储机密、密码或令牌。
- 类别：`preference` · `decision` · `insight` · `fact` · `context`
- 边类型：`temporal` · `semantic` · `causal` · `entity`
- 每条洞见最多 8,000 个字符。