org-memory

使用组织模式文件进行结构化知识库和任务管理。使用“org” CLI 查询、变异、链接和搜索 org 文件和 org-roam 数据库。

## 概述（中文）

使用组织模式文件进行结构化知识库和任务管理。使用“org” CLI 查询、变异、链接和搜索 org 文件和 org-roam 数据库。

## 原文

# org-memory

Use the `org` CLI to maintain structured, linked, human-readable knowledge in org-mode files. Org files are plain text with rich structure: headlines, TODO states, tags, properties, timestamps, and links. Combined with org-roam, they form a knowledge graph backed by a SQLite database.

## Shortcuts

When your human uses these patterns, act on them directly.

### Org mutations

| Prefix | Alias | Action |
|---|---|---|
| `t:` | `Todo:` | Create TODO in human's org (extracts dates) |
| `d:` | `Done:` / `Finished:` | Mark a TODO as DONE |
| `s:` | | Reschedule a TODO |
| `r:` | `Note:` | Save to human's roam (knowledge/info) |
| `k:` | `Know:` / `Remember:` | Agent learns it (agent's knowledge base) |

### Behaviour modifiers

These prefixes change how you respond, not what you store.

| Prefix | Action |
|---|---|
| `v:` | Voice reply (TTS) |
| `?` | Research (web + files) |
| `@` | Roam lookup |
| `w:` | Work context (Remundo) |
| `!` | Urgent — act now |
| `q:` | Quick answer, no tools |

### Todo — create a task

`t: <text>` or `Todo: <text>` means "create a task." Extract any date or timeframe from the text and schedule it. If the text contains a relative date ("in 3 weeks", "by Friday", "next month"), compute the actual date and add `--scheduled <date>` or `--deadline <date>`.

Action: `org add "$ORG_MEMORY_HUMAN_DIR/inbox.org" '<title>' --todo TODO --scheduled <date> --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json`

Use `--deadline` instead of `--scheduled` when the text implies a hard due date ("by Friday", "due March 1st"). Use `--scheduled` for softer timing ("in 3 weeks", "next month", "tomorrow").

Examples:
- "t: submit taxes in 3 weeks" → `org add .../inbox.org 'Submit taxes' --todo TODO --scheduled 2026-03-18`
- "Todo: renew passport by June" → `org add .../inbox.org 'Renew passport' --todo TODO --deadline 2026-06-01`
- "t: call dentist tomorrow" → `org add .../inbox.org 'Call dentist' --todo TODO --scheduled 2026-02-26`
- "Todo: book flights" → `org add .../inbox.org 'Book flights' --todo TODO` (no date mentioned)

### Note — for the human

`r: <text>` or `Note: <text>` means "add this to MY org files." It is always a task or reminder for the *human*, not for the agent.

Action: `org add "$ORG_MEMORY_HUMAN_DIR/inbox.org" '<text>' --todo TODO -f json`

If the note includes a date or deadline, add `--scheduled <date>` or `--deadline <date>`. If there's no date, add it without one (the human will schedule it themselves, or ask you to).

Examples:
- "r: Buy groceries" → `org add .../inbox.org 'Buy groceries' --todo TODO`
- "Note: Review PR #42 by Friday" → `org add .../inbox.org 'Review PR #42' --todo TODO --deadline 2026-02-28`
- "r: we could add feature X to the app" → `org add .../inbox.org 'Add feature X to the app' --todo TODO`
- "Note: send email to Donna about safeguarding" → `org add .../inbox.org 'Send email to Donna about safeguarding' --todo TODO`

**Note vs Todo:** Both create TODO headings. The difference is intent — `t:` / `Todo:` signals a concrete task (always try to extract a date), while `r:` / `Note:` is broader (ideas, reminders, observations). When there's no date, add it without one.

**Edge case — ideas and observations:** If the human says "r: we could do X" or "Note: idea for Y", it's still a Note. They're telling you to write it down for them. Add it as a TODO. Don't create a roam node, don't put it in the agent's knowledge base.

### Schedule — reschedule a task

`s: <text>` means "reschedule this task." Search for the matching TODO and update its scheduled date.

Action:
1. Search: `org todo list --state TODO --search '<text>' -d "$ORG_MEMORY_HUMAN_DIR" -f json`
2. If exactly one match: `org schedule <custom_id> <date> -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json`
3. If multiple matches: show them to the human and ask which one
4. If no match: tell the human you couldn't find it

Examples:
- "s: taxes to next Friday" → find "taxes" TODO, reschedule to next Friday
- "s: dentist 2026-04-01" → find "dentist" TODO, reschedule to 2026-04-01

### Done — mark complete

`d: <text>`, `Done: <text>`, or `Finished: <text>` means "mark this task as DONE." Search for the matching TODO and set its state.

Action:
1. Search: `org todo list --state TODO --search '<text>' -d "$ORG_MEMORY_HUMAN_DIR" -f json`
2. If exactly one match: `org todo set <custom_id> DONE -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json`
3. If multiple matches: show them to the human and ask which one
4. If no match: tell the human you couldn't find it

Examples:
- "d: pay Nigel Kerry" → find and mark DONE
- "Finished: the PR review" → find and mark DONE
- "Done: groceries" → search for "groceries", mark DONE

### Know — for the agent

`k: <info>`, `Know: <info>`, or `Remember: <info>` means "store this in YOUR knowledge base for future recall." This is information the agent should retain across sessions.

Action: Search for an existing node first (`org roam node find`), then create or update.

Examples:
- "k: Sarah prefers morning meetings" → Create/update a node for Sarah in `$ORG_MEMORY_AGENT_DIR`
- "Remember: The API uses OAuth2, not API keys" → Create/update a node for the API in `$ORG_MEMORY_AGENT_DIR`

### After every write — confirm

After every mutation to either directory, print a line in this exact format:

```
org-memory: <action> <file-path>
```

Examples: `org-memory: added TODO to ~/org/human/inbox.org`, `org-memory: created node ~/org/agent/sarah.org`, `org-memory: updated ~/org/agent/sarah.org`.

**This is mandatory.** Never silently write to either directory. The human should always see what you did and where.

## Output format

All commands accept `-f json` for structured output with `{"ok":true,"data":...}` envelopes. Errors return `{"ok":false,"error":{"type":"...","message":"..."}}`. Always use `-f json`.

## Command safety

User-provided text (task titles, note content, search terms) must be single-quoted to prevent shell expansion. Double quotes allow `$(…)`, backticks, and variable interpolation — single quotes do not.

```bash
# Correct
org add "$ORG_MEMORY_HUMAN_DIR/inbox.org" 'User provided text' --todo TODO -f json

# Wrong — double quotes allow shell injection
org add "$ORG_MEMORY_HUMAN_DIR/inbox.org" "User provided text" --todo TODO -f json
```

If the text contains a literal single quote, escape it with `'\''`:

```bash
org add "$ORG_MEMORY_HUMAN_DIR/inbox.org" 'Don'\''t forget' --todo TODO -f json
```

For multi-line content, pipe via stdin instead of interpolating:

```bash
printf '%s' 'Long text here' | org append k4t --stdin -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
```

Environment variable paths (`$ORG_MEMORY_HUMAN_DIR`, etc.) must always be double-quoted to handle spaces, but never place user text inside double quotes.

## Discovery

Run `org schema` once to get a machine-readable description of all commands, arguments, and flags. Use this to construct valid commands without memorizing the interface.

## Setup

Configuration is via environment variables. Set them in `openclaw.json` so they are injected into every command automatically.

Required — set these to match your directory layout:

| Variable | Default | Purpose |
|---|---|---|
| `ORG_MEMORY_AGENT_DIR` | `~/org/alcuin` | Agent's org workspace directory |
| `ORG_MEMORY_AGENT_ROAM_DIR` | `~/org/alcuin/roam` | Agent's roam node directory |
| `ORG_MEMORY_AGENT_DATABASE_LOCATION` | `~/org/alcuin/roam/.org.db` | Agent's database |
| `ORG_MEMORY_HUMAN_DIR` | `~/org/human` | Human's org workspace directory |
| `ORG_MEMORY_HUMAN_ROAM_DIR` | `~/org/human/roam` | Human's roam node directory |
| `ORG_MEMORY_HUMAN_DATABASE_LOCATION` | `~/org/human/roam/.org.db` | Human's database |

Optional — these have sensible defaults:

| Variable | Default | Purpose |
|---|---|---|
| `