Skill: org-memory

Owner: DCPRevere

Summary: Structured knowledge base and task management using org-mode files. Query, mutate, link, and search org files and org-roam databases with the org CLI.

Tags: latest:0.3.1

Version history:

v0.3.1 | 2026-02-26T13:36:03.448Z | auto

org-memory 0.3.1 changelog:

• Added in-depth reference documentation: knowledge-management.md, memory-architecture.md, task-management.md.
• Clarified and restructured SKILL.md for improved onboarding and environment setup.
• Unified and simplified shortcut actions and command safety instructions in the documentation.
• Updated install metadata and refined environment variable requirements.
• Removed the legacy README.md file—key docs now live under references/.

v0.2.1 | 2026-02-20T15:11:02.202Z | auto

org-memory 0.2.1

• Added recommendations to run org index after initializing org directories for proper CUSTOM_ID auto-assignment and support for file-less commands.
• Updated usage instructions: headlines now receive auto-assigned custom_id on creation; follow-up commands referencing headlines should use this custom_id.
• Clarified difference between org note (for LOGBOOK metadata) and org append (for headline body content), with usage examples.
• Task management docs now begin with a recommended org today query for actionable tasks.
• Improved setup, initialization, and command usage explanation throughout documentation for clarity and accuracy.

v0.1.4 | 2026-02-16T11:08:49.322Z | auto

org-memory 0.1.4 changelog:

• Shortcut actions now require a confirmation line in the format: org-memory: <action> <file-path> after every write.
• Clarified that confirmations should be printed directly after acting on 'Remember' or 'Note' patterns, instead of asking for confirmation.
• Examples added for the new confirmation line to guide correct output.

v0.1.3 | 2026-02-11T16:19:19.261Z | auto

org-memory 0.1.3

• No file changes detected in this release.
• Documentation, usage instructions, and configuration details remain unchanged.
• No new features, bug fixes, or updates introduced in this version.

v0.1.2 | 2026-02-11T16:15:48.072Z | auto

No user-visible changes in this release (version 0.1.2).

v0.1.1 | 2026-02-11T15:00:12.650Z | auto

No changes detected in this version.

• No file changes were found between versions.
• No new features, bug fixes, or documentation changes to report.

v0.1.0 | 2026-02-11T14:17:18.562Z | auto

Initial release of org-memory skill.

• Provides structured knowledge base and task management using org-mode files and the org CLI.
• Supports querying, updating, linking, and searching both org files and org-roam databases.
• Defines shortcut patterns ("Remember:", "Note:") for quickly capturing agent and human data.
• Ensures search-before-create discipline to prevent duplicate nodes in the knowledge graph.
• Includes guidance for setup, environment configuration, and command usage for both knowledge and task management.
• Supports batch operations for atomic multi-step updates.

Archive index:

Archive v0.3.1: 5 files, 10816 bytes

Files: references/knowledge-management.md (4662b), references/memory-architecture.md (5208b), references/task-management.md (5109b), SKILL.md (11233b), _meta.json (129b)

File v0.3.1:SKILL.md

---

name: org-memory version: 0.3.0 description: "Structured knowledge base and task management using org-mode files. Query, mutate, link, and search org files and org-roam databases with the org CLI." metadata: {"openclaw":{"emoji":"🦄","homepage":"https://github.com/dcprevere/org-cli","requires":{"bins":["org"],"env":["ORG_MEMORY_AGENT_DIR","ORG_MEMORY_HUMAN_DIR","ORG_MEMORY_AGENT_DATABASE_LOCATION","ORG_MEMORY_HUMAN_DATABASE_LOCATION"]},"install":[{"kind":"download","label":"Download from GitHub releases: https://github.com/dcprevere/org-cli/releases"}]}}

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.

| Keyword | Meaning | Target | |---|---|---| | Todo: | Create a task with a date | $ORG_MEMORY_HUMAN_DIR | | Note: | Write this down for me | $ORG_MEMORY_HUMAN_DIR | | Done: / Finished: | Mark a task complete | $ORG_MEMORY_HUMAN_DIR | | Know: | Store this for agent recall | $ORG_MEMORY_AGENT_DIR |

Todo — create a task

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:

• "Todo: 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
• "Todo: 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

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:

• "Note: 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
• "Note: 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 — Todo: signals a concrete task (always try to extract a date), while Note: is broader (ideas, reminders, observations). When there's no date, add it without one.

Edge case — ideas and observations: If the human says "Note: 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.

Done — mark complete

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

Action:

1. Search: org todos --state TODO --search '<text>' -d "$ORG_MEMORY_HUMAN_DIR" -f json
2. If exactly one match: org todo <file> '<title>' DONE -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:

• "Done: 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

Know: <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:

• "Know: Sarah prefers morning meetings" → Create/update a node for Sarah in $ORG_MEMORY_AGENT_DIR
• "Know: 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.

# 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 '\'':

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:

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.

| Variable | Default | Purpose | |---|---|---| | ORG_MEMORY_USE_FOR_AGENT | true | Enable the agent's own knowledge base | | ORG_MEMORY_AGENT_DIR | ~/org/agent | Agent's org directory | | ORG_MEMORY_AGENT_DATABASE_LOCATION | ~/.local/share/org-memory/agent/.org.db | Agent's database | | ORG_MEMORY_USE_FOR_HUMAN | true | Enable task management in the human's org files | | ORG_MEMORY_HUMAN_DIR | ~/org/human | Human's org directory | | ORG_MEMORY_HUMAN_DATABASE_LOCATION | ~/.local/share/org-memory/human/.org.db | Human's database |

If ORG_MEMORY_USE_FOR_AGENT is not true, skip the Knowledge management section. If ORG_MEMORY_USE_FOR_HUMAN is not true, skip the Task management and Batch operations sections.

Always pass --db to point at the correct database. The CLI auto-syncs the roam database after every mutation using the --db value. Without --db, the CLI defaults to the emacs org-roam database (~/.emacs.d/org-roam.db), which is not what you want.

Initialize each enabled directory. If the directories already contain org files, sync them first:

# Sync existing files into the roam database (skip if starting fresh)
org roam sync -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION"
org roam sync -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION"

# Create a seed node for the agent's knowledge base (skip if files already exist)
org roam node create 'Index' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

# Build the headline index (enables CUSTOM_ID auto-assignment and file-less commands)
org index -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION"
org index -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION"

The roam response includes the node's ID, file path, title, and tags.

Stable identifiers (CUSTOM_ID)

Every headline created with org add is auto-assigned a short CUSTOM_ID (e.g. k4t) when an index database exists. This ID appears in the custom_id field of all JSON responses and as a column in text output.

Use CUSTOM_IDs to refer to headlines in subsequent commands — they are stable across edits and don't require a file path:

org todo k4t DONE -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json
org schedule k4t 2026-03-15 -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json
org note k4t 'Pushed back per manager request' -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json
org append k4t 'Updated scope per review.' -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json

To backfill CUSTOM_IDs on existing headlines that don't have them:

org custom-id assign -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION"

Never address headlines by position number (pos). Positions change when files are edited — a mutation on one headline shifts the byte positions of everything after it.

Safe identifiers (in order of preference):

1. CUSTOM_ID (e.g. k4t) — stable, short, unique
2. org-id (UUID) — stable, unique
3. Exact title — stable as long as the title doesn't change

If you need to mutate multiple headlines in the same file, either:

• Use org batch for atomic multi-step operations (recommended)
• Use CUSTOM_IDs or titles, never pos
• If you must use pos, re-query after each mutation to get fresh positions

Error handling

Branch on the ok field. Handle errors by type:

• file_not_found: wrong path or deleted file
• headline_not_found: identifier doesn't match; re-query to get current state
• parse_error: file has syntax the parser can't handle; don't retry
• invalid_args: check org schema or org <command> --help

References

Read these on demand when the conversation requires them:

• Knowledge management ({baseDir}/references/knowledge-management.md): Read when ORG_MEMORY_USE_FOR_AGENT=true and you need to create/query/link roam nodes in the agent's knowledge base.
• Task management ({baseDir}/references/task-management.md): Read when ORG_MEMORY_USE_FOR_HUMAN=true and you need to query or mutate the human's tasks, use batch operations, or map natural-language queries to commands.
• Memory architecture ({baseDir}/references/memory-architecture.md): Read on first use (memory migration) and at session start (file structure, session routine, ambient capture guidelines).

File v0.3.1:_meta.json

{ "ownerId": "kn70zj1ajbxmgxbsfrw0nbtv9580p7ap", "slug": "org-memory", "version": "0.3.1", "publishedAt": 1772112963448 }

File v0.3.1:references/knowledge-management.md

Knowledge management

This section applies when ORG_MEMORY_USE_FOR_AGENT is true. All commands operate against $ORG_MEMORY_AGENT_DIR and $ORG_MEMORY_AGENT_DATABASE_LOCATION.

Always search before creating

Before creating a node or link, check if the entity already exists:

org roam node find 'Sarah' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

• If found: use the existing node's ID and file path
• If not found (headline_not_found error): create a new node

Never create a node without searching first. Duplicates fragment your knowledge graph.

Record an entity

Only after confirming no existing node:

org roam node create 'Sarah' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -t person -t work -f json

Add structure to a node

Use the file path returned by create/find commands:

# Add a headline to the node (response includes auto-assigned custom_id)
org add <file> 'Unavailable March 2026' --tag scheduling --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
# → {"ok":true,"data":{"custom_id":"k4t","title":"Unavailable March 2026",...}}

# Use the custom_id for follow-up commands
org note k4t 'Out all of March per human.' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

# Append body text to an existing headline
org append k4t 'Confirmed by email on 2026-02-20.' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

# Append multi-line text via stdin
printf '%s' 'First paragraph.

Second paragraph.' | org append k4t --stdin -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

org note vs org append: note adds a timestamped entry to the LOGBOOK drawer (metadata). append adds text to the headline body (visible content). Use note for audit trail, append for building up content.

Note: Both commands attach to headlines, not file-level nodes. If a roam node is file-level (no headlines yet), first add a headline with org add, then use note or append on it.

Link two nodes

Always search for both nodes first to get their IDs:

# Find source node
org roam node find 'Bob' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
# → Returns {"ok":true,"data":{"id":"e5f6a7b8-...","file":"/path/to/bob.org",...}}

# Find target node
org roam node find 'Alice' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
# → Returns {"ok":true,"data":{"id":"a1b2c3d4-...",...}}

If either node doesn't exist, create it first. Then link using the IDs from the responses:

org roam link add <source-file> '<source-id>' '<target-id>' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" --description 'manages' -f json

The --description is optional metadata about the relationship.

Query your knowledge

# Find a node by name
org roam node find 'Sarah' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

# Read a headline's full content (body, properties, logbook)
org read <file> 'Unavailable March 2026' -d "$ORG_MEMORY_AGENT_DIR" -f json

# Full-text search across all indexed headlines (fast, supports boolean/prefix/phrase)
org fts 'sarah AND march' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

# Regex search (slower, use when FTS isn't precise enough)
org search 'Sarah.*March' -d "$ORG_MEMORY_AGENT_DIR" -f json

# Browse by graph structure
org roam backlinks 'a1b2c3d4-...' -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
org roam tag find person -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

org fts vs org search: Use fts by default — it's faster and handles natural language well. Use search when you need regex patterns (e.g. matching across fields or partial words that aren't prefixes).

Aliases and refs

Aliases let a node be found by multiple names. Refs associate URLs or external identifiers.

org roam alias add <file> 'a1b2c3d4-...' 'Sarah Chen' --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION"
org roam ref add <file> 'a1b2c3d4-...' 'https://github.com/sarahchen' --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION"

Node conventions

Use consistent tags for easy querying:

• person — people the human knows or works with
• project — software projects, initiatives
• lesson — things the agent learned the hard way
• preference — how the human likes things done
• fact — technical details, configuration, reference data

File v0.3.1:references/memory-architecture.md

Memory architecture

$ORG_MEMORY_AGENT_DIR is the agent's primary long-term memory. It replaces flat memory files (like MEMORY.md) with a structured, searchable knowledge graph.

When org-memory is the primary memory system (i.e. the user said yes during migration and plugins.slots.memory is "none"): do not read or write MEMORY.md, and do not call memory_search or memory_get. All long-term memory goes through org files — memory.org, daily files, and entity nodes.

Memory migration

On first use, check whether the user wants org-memory to replace OpenClaw's default memory system.

1. Ask the user: "Would you like org-memory to be your primary memory system? This replaces MEMORY.md and daily files with org-mode equivalents."

2. If yes:

   a. Migrate MEMORY.md. Read ~/.openclaw/workspace/MEMORY.md. Convert markdown headings to org headings (# → * , ## → ** , etc.) and write the result to $ORG_MEMORY_AGENT_DIR/memory.org. If the file is empty or missing, create a minimal memory.org with a single top-level heading.

   b. Migrate daily files. For each ~/.openclaw/workspace/memory/YYYY-MM-DD.md, convert headings the same way and write to $ORG_MEMORY_AGENT_DIR/daily/YYYY-MM-DD.org. Create the daily/ directory if needed.

   c. Disable default memory plugin. Update ~/.openclaw/openclaw.json — set plugins.slots.memory to "none". This stops OpenClaw from loading memory_search/memory_get and prevents auto-flush to MEMORY.md during compaction.

   {
     "plugins": {
       "slots": {
         "memory": "none"
       }
     }
   }
   

   Merge this into the existing JSON — don't overwrite other keys.

   d. Sync. Run org roam sync and org index against $ORG_MEMORY_AGENT_DIR so the new files are in the database.

3. If no: Leave the default memory system active. The skill still provides knowledge graph (roam nodes, entity linking) and task management, but MEMORY.md remains the agent's primary curated memory. Do not write to memory.org or daily org files — those sections of the skill only apply when org-memory is the primary memory system.

File structure

$ORG_MEMORY_AGENT_DIR/
├── memory.org          # Curated long-term memory (read every session)
├── daily/
│   ├── 2026-02-21.org # Today's raw log
│   ├── 2026-02-20.org # Yesterday's raw log
│   └── ...
└── *.org              # Entity nodes (people, projects, etc.)

memory.org — the agent's permanent memory. Curated, concise, always loaded. Contains who the human is, active projects, lessons learned, conventions, and anything needed every session. Keep it tight — move detail into entity nodes and keep memory.org as a summary with links.

daily/YYYY-MM-DD.org — raw daily logs. What happened, decisions made, ambient facts captured, things learned. Working notes, not curated. Write freely.

Entity nodes (*.org) — structured roam nodes for people, projects, concepts. Tagged, linked, and queryable on demand.

Session start routine

At the start of every session:

1. Read memory.org — your permanent memory, always relevant
2. Read today and yesterday's daily files (daily/YYYY-MM-DD.org) — recent context
3. Load today's agenda: org today -d "$ORG_MEMORY_HUMAN_DIR" -f json

That's it. Don't load everything. Query entity nodes on demand when the conversation needs them.

During the session

• Ambient facts → append to today's daily file (daily/YYYY-MM-DD.org)
• New entity → create a roam node, then link from today's daily file
• Update to existing entity → org roam node find, then org append to the node
• Something worth keeping permanently → also update memory.org

Ambient capture

Not everything the human tells you is a command. Sometimes they mention facts in passing — a person's preference, a date, a technical detail, a relationship. Capture these in $ORG_MEMORY_AGENT_DIR without being asked, but only when the information has lasting value (people, decisions, technical details, preferences). Don't capture routine operational chatter.

Process: Complete the human's explicit request first. Then silently search for an existing node and update it (or create one if new). Always print org-memory: <action> <file-path> afterward.

Example: "Cancel my Thursday meeting with Sarah and reschedule the API migration review to next week. Sarah is going to be out all of March."

• Cancel and reschedule: explicit requests → execute in $ORG_MEMORY_HUMAN_DIR
• Sarah out all of March: ambient information → record in $ORG_MEMORY_AGENT_DIR
• Do both. Don't choose one or the other.

Memory maintenance

Periodically (every few days, during a quiet moment):

1. Review recent daily files
2. Promote important facts to entity nodes or memory.org
3. Remove outdated info from memory.org
4. Daily files can accumulate — they're cheap and searchable via org fts

This is like reviewing a journal and updating your mental model. Daily files are raw notes; memory.org is curated wisdom; entity nodes are structured knowledge.

File v0.3.1:references/task-management.md

Task management

This section applies when ORG_MEMORY_USE_FOR_HUMAN is true. All commands operate against $ORG_MEMORY_HUMAN_DIR and $ORG_MEMORY_HUMAN_DATABASE_LOCATION.

Read the human's state

Start here. org today is the most useful query — it returns all non-done TODOs that are scheduled for today or overdue:

org today -d "$ORG_MEMORY_HUMAN_DIR" -f json

For broader views:

org agenda today -d "$ORG_MEMORY_HUMAN_DIR" -f json   # all scheduled + deadlines for today
org agenda week -d "$ORG_MEMORY_HUMAN_DIR" -f json    # next 7 days
org agenda todo -d "$ORG_MEMORY_HUMAN_DIR" -f json    # all TODOs with scheduled dates
org agenda todo --tag work -d "$ORG_MEMORY_HUMAN_DIR" -f json

For rich filtering across all TODOs (scheduled or not):

org todos --state TODO -d "$ORG_MEMORY_HUMAN_DIR" -f json                    # all open TODOs
org todos --state TODO --unscheduled -d "$ORG_MEMORY_HUMAN_DIR" -f json      # unscheduled only
org todos --state TODO --overdue -d "$ORG_MEMORY_HUMAN_DIR" -f json          # overdue items
org todos --state TODO --due-before 2026-03-01 -d "$ORG_MEMORY_HUMAN_DIR" -f json  # due before date
org todos --search 'meeting' -d "$ORG_MEMORY_HUMAN_DIR" -f json              # search by title
org todos --state TODO --file 'work' -d "$ORG_MEMORY_HUMAN_DIR" -f json      # filter by file
org todos --state TODO --tag urgent -d "$ORG_MEMORY_HUMAN_DIR" -f json       # filter by tag
org todos --state TODO --priority A -d "$ORG_MEMORY_HUMAN_DIR" -f json       # filter by priority
org todos --state TODO --sort priority -d "$ORG_MEMORY_HUMAN_DIR" -f json    # sort by priority
org todos --state TODO --sort scheduled --reverse -d "$ORG_MEMORY_HUMAN_DIR" -f json  # reverse sort

The todos command returns full data in JSON: title, todo state, priority, tags, file, pos, scheduled, deadline, level, path (parent headlines), and custom_id. All filters are combinable.

Make changes

# Add a headline (response includes the auto-assigned custom_id)
org add "$ORG_MEMORY_HUMAN_DIR/inbox.org" 'Review PR #42' --todo TODO --tag work --deadline 2026-02-10 --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json

# Subsequent commands use the custom_id — no file path needed
org todo k4t DONE -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json
org schedule a1b 2026-03-15 -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json
org note a1b 'Pushed back per manager request' -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION"
org append a1b 'Meeting notes from standup.' -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json

# Refile still requires explicit file paths
org refile "$ORG_MEMORY_HUMAN_DIR/inbox.org" 'Review PR #42' "$ORG_MEMORY_HUMAN_DIR/work.org" 'Code reviews' --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json

Preview before writing

Use --dry-run to see what a mutation would produce without modifying the file:

org todo tasks.org 'Buy groceries' DONE --dry-run -f json

Batch operations

Apply multiple mutations atomically. Commands execute sequentially against in-memory state. Files are written only if all succeed.

echo '{"commands":[
  {"command":"todo","file":"tasks.org","identifier":"Buy groceries","args":{"state":"DONE"}},
  {"command":"tag-add","file":"tasks.org","identifier":"Write report","args":{"tag":"urgent"}},
  {"command":"schedule","file":"tasks.org","identifier":"Write report","args":{"date":"2026-03-01"}},
  {"command":"append","file":"tasks.org","identifier":"Write report","args":{"text":"Include Q1 metrics."}}
]}' | org batch -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json

Query shortcuts

When the human asks about their tasks or your knowledge, map natural language to the right query. Don't ask "what do you mean?" — just run the query.

| Human says | Action | |---|---| | "What do I need to do?" / "What's on my plate?" | org today -d "$ORG_MEMORY_HUMAN_DIR" -f json (today + overdue) | | "What's overdue?" | org todos --state TODO --overdue -d "$ORG_MEMORY_HUMAN_DIR" -f json | | "What's coming up this week?" | org agenda week -d "$ORG_MEMORY_HUMAN_DIR" -f json | | "Show me everything tagged work" | org todos --state TODO --tag work -d "$ORG_MEMORY_HUMAN_DIR" -f json | | "What do I have unscheduled?" | org todos --state TODO --unscheduled -d "$ORG_MEMORY_HUMAN_DIR" -f json | | "Find all tasks about X" | org todos --search 'X' -d "$ORG_MEMORY_HUMAN_DIR" -f json | | "What do you know about Sarah?" | org roam node find 'Sarah' → org read <file> 'Sarah' → org roam backlinks <id> (all with agent dir/db flags) | | "What's the status of project X?" | org fts 'X' -d "$ORG_MEMORY_AGENT_DIR" + org todos --search 'X' -d "$ORG_MEMORY_HUMAN_DIR" | | "Search my notes for Y" | org fts 'Y' -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json |

Present results in a clean, readable format. Don't dump raw JSON at the human — summarise it.

Archive v0.2.1: 3 files, 7269 bytes

Files: README.md (5186b), SKILL.md (12999b), _meta.json (129b)

File v0.2.1:SKILL.md

---

name: org-memory description: "Structured knowledge base and task management using org-mode files. Query, mutate, link, and search org files and org-roam databases with the org CLI." metadata: {"openclaw":{"emoji":"🦄","requires":{"bins":["org"]},"install":[{"id":"github-release","kind":"manual","label":"Download from GitHub releases: https://github.com/dcprevere/org-cli/releases"}]}}

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 immediately:

| Pattern | Action | |---------|--------| | Remember: <info> | Save to your knowledge base ($ORG_MEMORY_AGENT_DIR). Create or update a node. This is for your future recall. | | Note: <task or info> | Add to the human's org files ($ORG_MEMORY_HUMAN_DIR/inbox.org). This is for them to act on. |

Examples:

• "Remember: Sarah prefers morning meetings" → Create/update a node for Sarah in your repo
• "Note: Buy groceries" → Add a TODO to the human's inbox
• "Remember: The API uses OAuth2, not API keys" → Create/update a node for the API in your repo
• "Note: Review PR #42 by Friday" → Add a TODO with deadline to the human's inbox

Don't ask for confirmation on shortcuts — just do it. After every write, 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.

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.

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.

| Variable | Default | Purpose | |---|---|---| | ORG_MEMORY_USE_FOR_AGENT | true | Enable the agent's own knowledge base | | ORG_MEMORY_AGENT_DIR | ~/org/agent | Agent's org directory | | ORG_MEMORY_AGENT_DATABASE_LOCATION | ~/.local/share/org-memory/agent/.org.db | Agent's database | | ORG_MEMORY_USE_FOR_HUMAN | true | Enable task management in the human's org files | | ORG_MEMORY_HUMAN_DIR | ~/org/human | Human's org directory | | ORG_MEMORY_HUMAN_DATABASE_LOCATION | ~/.local/share/org-memory/human/.org.db | Human's database |

If ORG_MEMORY_USE_FOR_AGENT is not true, skip the Knowledge management section. If ORG_MEMORY_USE_FOR_HUMAN is not true, skip the Task management and Batch operations sections.

Always pass --db to point at the correct database. The CLI auto-syncs the roam database after every mutation using the --db value. Without --db, the CLI defaults to the emacs org-roam database (~/.emacs.d/org-roam.db), which is not what you want.

Initialize each enabled directory by creating a first node and building the headline index:

org roam node create "Index" -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
org index -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION"
org index -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION"

The roam response includes the node's ID, file path, title, and tags. The index enables CUSTOM_ID auto-assignment and file-less commands.

Knowledge management

This section applies when ORG_MEMORY_USE_FOR_AGENT is true.

⚠️ Always search before creating

Before creating a node or link, check if the entity already exists:

org roam node find "Sarah" -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

• If found: use the existing node's ID and file path
• If not found (headline_not_found error): create a new node

Never create a node without searching first. Duplicates fragment your knowledge graph.

Record an entity

Only after confirming no existing node:

org roam node create "Sarah" -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -t person -t work -f json

Add structure to a node

Use the file path returned by create/find commands:

# Add a headline to the node (response includes auto-assigned custom_id)
org add <file> "Unavailable March 2026" --tag scheduling --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
# → {"ok":true,"data":{"custom_id":"k4t","title":"Unavailable March 2026",...}}

# Use the custom_id for follow-up commands
org note k4t "Out all of March per human." -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

# Append body text to an existing headline
org append k4t "Confirmed by email on 2026-02-20." -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

# Append multi-line text via stdin
echo "First paragraph.\n\nSecond paragraph." | org append k4t --stdin -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json

org note vs org append: note adds a timestamped entry to the LOGBOOK drawer (metadata). append adds text to the headline body (visible content). Use note for audit trail, append for building up content.

Note: Both commands attach to headlines, not file-level nodes. If a roam node is file-level (no headlines yet), first add a headline with org add, then use note or append on it.

Link two nodes

Always search for both nodes first to get their IDs:

# Find source node
org roam node find "Bob" -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
# → Returns {"ok":true,"data":{"id":"e5f6a7b8-...","file":"/path/to/bob.org",...}}

# Find target node  
org roam node find "Alice" -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
# → Returns {"ok":true,"data":{"id":"a1b2c3d4-...",...}}

If either node doesn't exist, create it first. Then link using the IDs from the responses:

org roam link add <source-file> "<source-id>" "<target-id>" -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" --description "manages" -f json

The --description is optional metadata about the relationship.

Query your knowledge

org roam node find "Sarah" -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
org roam backlinks "a1b2c3d4-..." -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
org roam tag find person -d "$ORG_MEMORY_AGENT_DIR" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION" -f json
org search "Sarah.*March" -d "$ORG_MEMORY_AGENT_DIR" -f json

Add aliases and refs

Aliases let a node be found by multiple names. Refs associate URLs or external identifiers.

org roam alias add <file> "a1b2c3d4-..." "Sarah Chen" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION"
org roam ref add <file> "a1b2c3d4-..." "https://github.com/sarahchen" --db "$ORG_MEMORY_AGENT_DATABASE_LOCATION"

Task management

This section applies when ORG_MEMORY_USE_FOR_HUMAN is true.

Read the human's state

Start here. org today is the most useful query — it returns all non-done TODOs that are scheduled for today or overdue:

org today -d "$ORG_MEMORY_HUMAN_DIR" -f json

For broader views:

org agenda today -d "$ORG_MEMORY_HUMAN_DIR" -f json   # all scheduled + deadlines for today
org agenda week -d "$ORG_MEMORY_HUMAN_DIR" -f json    # next 7 days
org agenda todo -d "$ORG_MEMORY_HUMAN_DIR" -f json    # all TODOs
org agenda todo --tag work -d "$ORG_MEMORY_HUMAN_DIR" -f json

Make changes

# Add a headline (response includes the auto-assigned custom_id)
org add $ORG_MEMORY_HUMAN_DIR/inbox.org "Review PR #42" --todo TODO --tag work --deadline 2026-02-10 --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json

# Subsequent commands use the custom_id — no file path needed
org todo k4t DONE -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json
org schedule a1b 2026-03-15 -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json
org note a1b "Pushed back per manager request" -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION"
org append a1b "Meeting notes from standup." -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json

# Refile still requires explicit file paths
org refile $ORG_MEMORY_HUMAN_DIR/inbox.org "Review PR #42" $ORG_MEMORY_HUMAN_DIR/work.org "Code reviews" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json

Preview before writing

Use --dry-run to see what a mutation would produce without modifying the file:

org todo tasks.org "Buy groceries" DONE --dry-run -f json

Batch operations

This section applies when ORG_MEMORY_USE_FOR_HUMAN is true.

Apply multiple mutations atomically. Commands execute sequentially against in-memory state. Files are written only if all succeed.

echo '{"commands":[
  {"command":"todo","file":"tasks.org","identifier":"Buy groceries","args":{"state":"DONE"}},
  {"command":"tag-add","file":"tasks.org","identifier":"Write report","args":{"tag":"urgent"}},
  {"command":"schedule","file":"tasks.org","identifier":"Write report","args":{"date":"2026-03-01"}},
  {"command":"append","file":"tasks.org","identifier":"Write report","args":{"text":"Include Q1 metrics."}}
]}' | org batch -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json

When to record knowledge

When both features are enabled and the human tells you something, distinguish between requests and ambient information. Fulfill requests in $ORG_MEMORY_HUMAN_DIR. Record what you learned in $ORG_MEMORY_AGENT_DIR.

Example: "Cancel my Thursday meeting with Sarah and reschedule the API migration review to next week. Sarah is going to be out all of March."

• Cancel and reschedule: explicit requests, execute in $ORG_MEMORY_HUMAN_DIR
• Sarah out all of March: ambient information, record in $ORG_MEMORY_AGENT_DIR

If only agent memory is enabled, record everything relevant in $ORG_MEMORY_AGENT_DIR. If only human file management is enabled, only act on explicit requests.

Check whether a node already exists before creating it. Use the returned data from mutations rather than making follow-up queries.

Always report writes. After every mutation to either directory, print org-memory: <action> <file-path>. Never silently write to either directory.

Stable identifiers (CUSTOM_ID)

Every headline created with org add is auto-assigned a short CUSTOM_ID (e.g. k4t) when an index database exists. This ID appears in the custom_id field of all JSON responses and as a column in text output.

Use CUSTOM_IDs to refer to headlines in subsequent commands — they are stable across edits and don't require a file path:

org todo k4t DONE -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json
org schedule k4t 2026-03-15 -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json
org note k4t "Pushed back per manager request" -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json
org append k4t "Updated scope per review." -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION" -f json

To backfill CUSTOM_IDs on existing headlines that don't have them:

org custom-id assign -d "$ORG_MEMORY_HUMAN_DIR" --db "$ORG_MEMORY_HUMAN_DATABASE_LOCATION"

Never address headlines by position number. Positions change when files are edited. Use CUSTOM_ID, org-id, or exact title.

Error handling

Branch on the ok field. Handle errors by type:

• file_not_found: wrong path or deleted file
• headline_not_found: identifier doesn't match; re-query to get current state
• parse_error: file has syntax the parser can't handle; don't retry
• invalid_args: check org schema or org <command> --help

Troubleshooting

Duplicate nodes created

You didn't search before creating. Always run node find first. If duplicates exist, manually delete the newer file and run org roam sync.

"headline_not_found" when using org note

You tried to add a note to a file-level node (level 0). Use org add to create a headline first, then org note on that headline.

Links show wrong display text

The --description parameter sets relationship metadata, not display text. The link displays the target node's title. This is correct org-roam behavior.

Database out of sync

Run org roam sync -d <dir> --db <db-path> to rebuild the database from files.

File v0.2.1:README.md

org-memory

An OpenClaw skill that gives your agent structured, linked, human-readable memory using org-mode files.

Install

1. Put org on your PATH (releases).

2. Copy the skill into your OpenClaw skills directory:

cp -r integrations/openclaw ~/.openclaw/skills/org-memory

1. Ask your agent to "refresh skills" or restart the gateway.

Quick start

Once installed, just talk to your agent naturally:

• "Remember: Sarah prefers morning meetings" → Agent saves to its knowledge base
• "Note: Buy groceries" → Agent adds TODO to your inbox
• "What do you know about Sarah?" → Agent queries its knowledge

When to use org-memory

OpenClaw's default memory (MEMORY.md + semantic search) works well for simple setups. org-memory is worth the added complexity when you need more.

org-memory vs MEMORY.md

| Capability | MEMORY.md | org-memory | |------------|-----------|------------| | Store facts about one person | Works great | Overkill | | Store 20+ entities (people, projects, companies) | Gets messy | Each entity = separate file | | "List all my clients" | Grep through text | tag find client → structured list | | Track relationships | Text references | Graph links with backlinks | | "What do I need to do today?" | Not possible | org today → due + overdue TODOs | | "What's due this week?" | Not possible | agenda week → parsed dates | | Task management | No date support | SCHEDULED, DEADLINE, repeaters | | "Mark that task done" | Find file, find line | org todo k4t DONE |

Use MEMORY.md for: personal preferences, key dates, simple facts (<100 items).

Use org-memory for: CRM-like knowledge, task management, relationship graphs, or any knowledge base that will grow beyond 100 entities.

org-memory vs Obsidian

Both are linked knowledge graphs. Key differences:

| | Obsidian | org-memory | |---|----------|------------| | Format | Markdown + YAML frontmatter | Org-mode | | Task management | Limited (no native dates) | Full agenda: SCHEDULED, DEADLINE, repeaters, clock | | Query language | Dataview plugin (JS-based) | CLI with JSON output | | Human editing | Obsidian app or any editor | Emacs or any editor | | Agent integration | Needs custom tooling | Built for CLI/agent use |

Use Obsidian if: you already live in Obsidian and want your agent to share that vault.

Use org-memory if: you need real task management with dates, prefer CLI-native tooling, or use Emacs.

The killer feature

The real differentiator is agenda queries and short IDs. The moment you want:

• "What's due today?" → org today shows all non-done TODOs due today or overdue
• "Schedule this for next Monday"
• "Show me overdue tasks" → org today catches these automatically
• "Mark k4t as done" (no file path needed)

...MEMORY.md and Obsidian can't help. org-memory handles this natively because org-mode was built for it. Every headline gets a short CUSTOM_ID (like k4t) that works across files without remembering paths.

What it does

The skill teaches the agent to use org for:

• Knowledge graph: create nodes, link them, query by tag/title/backlink/search
• Task management: create/complete/schedule/refile tasks in the human's org files
• Structured memory: record entities, relationships, and constraints as linked org-roam nodes instead of flat text
• Batch mutations: apply multiple changes atomically

By default the agent maintains two directories: its own knowledge base and the human's files. Either feature can be disabled independently. All files are plain text, human-readable, and version-controllable.

Configuration

| Variable | Default | Purpose | |---|---|---| | ORG_MEMORY_USE_FOR_AGENT | true | Enable the agent's own knowledge base | | ORG_MEMORY_AGENT_DIR | ~/org/agent | Agent's org directory | | ORG_MEMORY_AGENT_DATABASE_LOCATION | ~/.local/share/org-memory/agent/.org.db | Agent's database | | ORG_MEMORY_USE_FOR_HUMAN | true | Enable task management in the human's org files | | ORG_MEMORY_HUMAN_DIR | ~/org/human | Human's org directory | | ORG_MEMORY_HUMAN_DATABASE_LOCATION | ~/.local/share/org-memory/human/.org.db | Human's database |

All are optional. If unset, the defaults apply. Set ORG_MEMORY_USE_FOR_AGENT or ORG_MEMORY_USE_FOR_HUMAN to anything other than true to disable that feature.

The databases are stored under ~/.local/share/org-memory/ by default, separate from both the org files and the emacs org-roam database (~/.emacs.d/org-roam.db) to avoid concurrent-write conflicts. The org CLI itself defaults to the emacs database; the skill overrides this via --db.

To override, set them in ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "org-memory": {
        "env": {
          "ORG_MEMORY_USE_FOR_HUMAN": "false",
          "ORG_MEMORY_AGENT_DIR": "/path/to/agent",
          "ORG_MEMORY_AGENT_DATABASE_LOCATION": "/path/to/agent.db"
        }
      }
    }
  }
}

Or export them in your shell. Shell env takes precedence over openclaw.json.

File v0.2.1:_meta.json

{ "ownerId": "kn70zj1ajbxmgxbsfrw0nbtv9580p7ap", "slug": "org-memory", "version": "0.2.1", "publishedAt": 1771600262202 }