{"id":"d44d2fa1-cbc9-477c-a010-b50e461572e4","entityType":"agent","slug":"clawhub-dcprevere-org-memory","name":"org-memory","canonicalUrl":"https://xpersona.co/agent/clawhub-dcprevere-org-memory","canonicalPath":"/agent/clawhub-dcprevere-org-memory","generatedAt":"2026-04-17T06:14:54.483Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"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.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 745 downloads reported by the source. Last updated 4/15/2026.","installCommand":"clawhub skill install kn70zj1ajbxmgxbsfrw0nbtv9580p7ap:org-memory","sourceUrl":"https://clawhub.ai/DCPRevere/org-memory","homepage":"https://clawhub.ai/DCPRevere/org-memory","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/DCPRevere/org-memory","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":57,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"org-memory technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"stars":null,"forks":null,"downloads":745,"packageName":null,"latestVersion":"0.3.1","tractionLabel":"745 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-03-01T02:40:01.928Z","emptyReason":null},"lastUpdatedAt":"2026-04-15T00:45:39.800Z","lastCrawledAt":"2026-03-01T02:40:01.928Z","lastIndexedAt":null,"nextCrawlAt":"2026-03-02T02:40:01.928Z","lastVerifiedAt":null,"highlights":[{"version":"0.3.1","createdAt":"2026-02-26T13:36:03.448Z","changelog":"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/.","fileCount":5,"zipByteSize":10816},{"version":"0.2.1","createdAt":"2026-02-20T15:11:02.202Z","changelog":"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.","fileCount":3,"zipByteSize":7269},{"version":"0.1.4","createdAt":"2026-02-16T11:08:49.322Z","changelog":"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.","fileCount":null,"zipByteSize":null},{"version":"0.1.3","createdAt":"2026-02-11T16:19:19.261Z","changelog":"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.","fileCount":null,"zipByteSize":null},{"version":"0.1.2","createdAt":"2026-02-11T16:15:48.072Z","changelog":"No user-visible changes in this release (version 0.1.2).","fileCount":null,"zipByteSize":null},{"version":"0.1.1","createdAt":"2026-02-11T15:00:12.650Z","changelog":"No changes detected in this version. - No file changes were found between versions. - No new features, bug fixes, or documentation changes to report.","fileCount":null,"zipByteSize":null},{"version":"0.1.0","createdAt":"2026-02-11T14:17:18.562Z","changelog":"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.","fileCount":null,"zipByteSize":null}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install kn70zj1ajbxmgxbsfrw0nbtv9580p7ap:org-memory","setupComplexity":"low","setupSteps":["Install using `clawhub skill install kn70zj1ajbxmgxbsfrw0nbtv9580p7ap:org-memory` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/DCPRevere/org-memory before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://xpersona.co/api/v1/agents/clawhub-dcprevere-org-memory/snapshot","contractUrl":"https://xpersona.co/api/v1/agents/clawhub-dcprevere-org-memory/contract","trustUrl":"https://xpersona.co/api/v1/agents/clawhub-dcprevere-org-memory/trust"},"curlExamples":["curl -s \"https://xpersona.co/api/v1/agents/clawhub-dcprevere-org-memory/snapshot\"","curl -s \"https://xpersona.co/api/v1/agents/clawhub-dcprevere-org-memory/contract\"","curl -s \"https://xpersona.co/api/v1/agents/clawhub-dcprevere-org-memory/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-04-17T06:14:54.482Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://xpersona.co/api/v1/agents/clawhub-dcprevere-org-memory/dossier","snapshotUrl":"https://xpersona.co/api/v1/agents/clawhub-dcprevere-org-memory/snapshot","contractUrl":"https://xpersona.co/api/v1/agents/clawhub-dcprevere-org-memory/contract","trustUrl":"https://xpersona.co/api/v1/agents/clawhub-dcprevere-org-memory/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"readme":"Skill: org-memory\n\nOwner: DCPRevere\n\nSummary: 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.\n\nTags: latest:0.3.1\n\nVersion history:\n\nv0.3.1 | 2026-02-26T13:36:03.448Z | auto\n\norg-memory 0.3.1 changelog:\n\n- Added in-depth reference documentation: knowledge-management.md, memory-architecture.md, task-management.md.\n- Clarified and restructured SKILL.md for improved onboarding and environment setup.\n- Unified and simplified shortcut actions and command safety instructions in the documentation.\n- Updated install metadata and refined environment variable requirements.\n- Removed the legacy README.md file—key docs now live under references/.\n\nv0.2.1 | 2026-02-20T15:11:02.202Z | auto\n\norg-memory 0.2.1\n\n- Added recommendations to run `org index` after initializing org directories for proper CUSTOM_ID auto-assignment and support for file-less commands.\n- Updated usage instructions: headlines now receive auto-assigned `custom_id` on creation; follow-up commands referencing headlines should use this `custom_id`.\n- Clarified difference between `org note` (for LOGBOOK metadata) and `org append` (for headline body content), with usage examples.\n- Task management docs now begin with a recommended `org today` query for actionable tasks.\n- Improved setup, initialization, and command usage explanation throughout documentation for clarity and accuracy.\n\nv0.1.4 | 2026-02-16T11:08:49.322Z | auto\n\norg-memory 0.1.4 changelog:\n\n- Shortcut actions now require a confirmation line in the format: `org-memory: <action> <file-path>` after every write.\n- Clarified that confirmations should be printed directly after acting on 'Remember' or 'Note' patterns, instead of asking for confirmation.\n- Examples added for the new confirmation line to guide correct output.\n\nv0.1.3 | 2026-02-11T16:19:19.261Z | auto\n\norg-memory 0.1.3\n\n- No file changes detected in this release.\n- Documentation, usage instructions, and configuration details remain unchanged.\n- No new features, bug fixes, or updates introduced in this version.\n\nv0.1.2 | 2026-02-11T16:15:48.072Z | auto\n\nNo user-visible changes in this release (version 0.1.2).\n\nv0.1.1 | 2026-02-11T15:00:12.650Z | auto\n\nNo changes detected in this version.\n\n- No file changes were found between versions.\n- No new features, bug fixes, or documentation changes to report.\n\nv0.1.0 | 2026-02-11T14:17:18.562Z | auto\n\nInitial release of org-memory skill.\n\n- Provides structured knowledge base and task management using org-mode files and the `org` CLI.\n- Supports querying, updating, linking, and searching both org files and org-roam databases.\n- Defines shortcut patterns (\"Remember:\", \"Note:\") for quickly capturing agent and human data.\n- Ensures search-before-create discipline to prevent duplicate nodes in the knowledge graph.\n- Includes guidance for setup, environment configuration, and command usage for both knowledge and task management.\n- Supports batch operations for atomic multi-step updates.\n\nArchive index:\n\nArchive v0.3.1: 5 files, 10816 bytes\n\nFiles: references/knowledge-management.md (4662b), references/memory-architecture.md (5208b), references/task-management.md (5109b), SKILL.md (11233b), _meta.json (129b)\n\nFile v0.3.1:SKILL.md\n\n---\nname: org-memory\nversion: 0.3.0\ndescription: \"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.\"\nmetadata: {\"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\"}]}}\n---\n\n# org-memory\n\nUse 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.\n\n## Shortcuts\n\nWhen your human uses these patterns, act on them directly.\n\n| Keyword | Meaning | Target |\n|---|---|---|\n| `Todo:` | Create a task with a date | `$ORG_MEMORY_HUMAN_DIR` |\n| `Note:` | Write this down for me | `$ORG_MEMORY_HUMAN_DIR` |\n| `Done:` / `Finished:` | Mark a task complete | `$ORG_MEMORY_HUMAN_DIR` |\n| `Know:` | Store this for agent recall | `$ORG_MEMORY_AGENT_DIR` |\n\n### Todo — create a task\n\n`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>`.\n\nAction: `org add \"$ORG_MEMORY_HUMAN_DIR/inbox.org\" '<title>' --todo TODO --scheduled <date> --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json`\n\nUse `--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\").\n\nExamples:\n- \"Todo: submit taxes in 3 weeks\" → `org add .../inbox.org 'Submit taxes' --todo TODO --scheduled 2026-03-18`\n- \"Todo: renew passport by June\" → `org add .../inbox.org 'Renew passport' --todo TODO --deadline 2026-06-01`\n- \"Todo: call dentist tomorrow\" → `org add .../inbox.org 'Call dentist' --todo TODO --scheduled 2026-02-26`\n- \"Todo: book flights\" → `org add .../inbox.org 'Book flights' --todo TODO` (no date mentioned)\n\n### Note — for the human\n\n`Note: <text>` means \"add this to MY org files.\" It is always a task or reminder for the *human*, not for the agent.\n\nAction: `org add \"$ORG_MEMORY_HUMAN_DIR/inbox.org\" '<text>' --todo TODO -f json`\n\nIf 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).\n\nExamples:\n- \"Note: Buy groceries\" → `org add .../inbox.org 'Buy groceries' --todo TODO`\n- \"Note: Review PR #42 by Friday\" → `org add .../inbox.org 'Review PR #42' --todo TODO --deadline 2026-02-28`\n- \"Note: we could add feature X to the app\" → `org add .../inbox.org 'Add feature X to the app' --todo TODO`\n- \"Note: send email to Donna about safeguarding\" → `org add .../inbox.org 'Send email to Donna about safeguarding' --todo TODO`\n\n**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.\n\n**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.\n\n### Done — mark complete\n\n`Done: <text>` or `Finished: <text>` means \"mark this task as DONE.\" Search for the matching TODO and set its state.\n\nAction:\n1. Search: `org todos --state TODO --search '<text>' -d \"$ORG_MEMORY_HUMAN_DIR\" -f json`\n2. If exactly one match: `org todo <file> '<title>' DONE -f json`\n3. If multiple matches: show them to the human and ask which one\n4. If no match: tell the human you couldn't find it\n\nExamples:\n- \"Done: pay Nigel Kerry\" → find and mark DONE\n- \"Finished: the PR review\" → find and mark DONE\n- \"Done: groceries\" → search for \"groceries\", mark DONE\n\n### Know — for the agent\n\n`Know: <info>` means \"store this in YOUR knowledge base for future recall.\" This is information the agent should retain across sessions.\n\nAction: Search for an existing node first (`org roam node find`), then create or update.\n\nExamples:\n- \"Know: Sarah prefers morning meetings\" → Create/update a node for Sarah in `$ORG_MEMORY_AGENT_DIR`\n- \"Know: The API uses OAuth2, not API keys\" → Create/update a node for the API in `$ORG_MEMORY_AGENT_DIR`\n\n### After every write — confirm\n\nAfter every mutation to either directory, print a line in this exact format:\n\n```\norg-memory: <action> <file-path>\n```\n\nExamples: `org-memory: added TODO to ~/org/human/inbox.org`, `org-memory: created node ~/org/agent/sarah.org`, `org-memory: updated ~/org/agent/sarah.org`.\n\n**This is mandatory.** Never silently write to either directory. The human should always see what you did and where.\n\n## Output format\n\nAll commands accept `-f json` for structured output with `{\"ok\":true,\"data\":...}` envelopes. Errors return `{\"ok\":false,\"error\":{\"type\":\"...\",\"message\":\"...\"}}`. Always use `-f json`.\n\n## Command safety\n\nUser-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.\n\n```bash\n# Correct\norg add \"$ORG_MEMORY_HUMAN_DIR/inbox.org\" 'User provided text' --todo TODO -f json\n\n# Wrong — double quotes allow shell injection\norg add \"$ORG_MEMORY_HUMAN_DIR/inbox.org\" \"User provided text\" --todo TODO -f json\n```\n\nIf the text contains a literal single quote, escape it with `'\\''`:\n\n```bash\norg add \"$ORG_MEMORY_HUMAN_DIR/inbox.org\" 'Don'\\''t forget' --todo TODO -f json\n```\n\nFor multi-line content, pipe via stdin instead of interpolating:\n\n```bash\nprintf '%s' 'Long text here' | org append k4t --stdin -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n```\n\nEnvironment variable paths (`$ORG_MEMORY_HUMAN_DIR`, etc.) must always be double-quoted to handle spaces, but never place user text inside double quotes.\n\n## Discovery\n\nRun `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.\n\n## Setup\n\nConfiguration is via environment variables. Set them in `openclaw.json` so they are injected into every command automatically.\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `ORG_MEMORY_USE_FOR_AGENT` | `true` | Enable the agent's own knowledge base |\n| `ORG_MEMORY_AGENT_DIR` | `~/org/agent` | Agent's org directory |\n| `ORG_MEMORY_AGENT_DATABASE_LOCATION` | `~/.local/share/org-memory/agent/.org.db` | Agent's database |\n| `ORG_MEMORY_USE_FOR_HUMAN` | `true` | Enable task management in the human's org files |\n| `ORG_MEMORY_HUMAN_DIR` | `~/org/human` | Human's org directory |\n| `ORG_MEMORY_HUMAN_DATABASE_LOCATION` | `~/.local/share/org-memory/human/.org.db` | Human's database |\n\nIf `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.\n\nAlways 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.\n\nInitialize each enabled directory. If the directories already contain org files, sync them first:\n\n```bash\n# Sync existing files into the roam database (skip if starting fresh)\norg roam sync -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\"\norg roam sync -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\"\n\n# Create a seed node for the agent's knowledge base (skip if files already exist)\norg roam node create 'Index' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n\n# Build the headline index (enables CUSTOM_ID auto-assignment and file-less commands)\norg index -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\"\norg index -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\"\n```\n\nThe roam response includes the node's ID, file path, title, and tags.\n\n## Stable identifiers (CUSTOM_ID)\n\nEvery 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.\n\nUse CUSTOM_IDs to refer to headlines in subsequent commands — they are stable across edits and don't require a file path:\n\n```bash\norg todo k4t DONE -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg schedule k4t 2026-03-15 -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg note k4t 'Pushed back per manager request' -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg append k4t 'Updated scope per review.' -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\n```\n\nTo backfill CUSTOM_IDs on existing headlines that don't have them:\n\n```bash\norg custom-id assign -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\"\n```\n\n**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.\n\nSafe identifiers (in order of preference):\n1. **CUSTOM_ID** (e.g. `k4t`) — stable, short, unique\n2. **org-id** (UUID) — stable, unique\n3. **Exact title** — stable as long as the title doesn't change\n\nIf you need to mutate multiple headlines in the same file, either:\n- Use `org batch` for atomic multi-step operations (recommended)\n- Use CUSTOM_IDs or titles, never `pos`\n- If you must use `pos`, re-query after each mutation to get fresh positions\n\n## Error handling\n\nBranch on the `ok` field. Handle errors by `type`:\n\n- `file_not_found`: wrong path or deleted file\n- `headline_not_found`: identifier doesn't match; re-query to get current state\n- `parse_error`: file has syntax the parser can't handle; don't retry\n- `invalid_args`: check `org schema` or `org <command> --help`\n\n## References\n\nRead these on demand when the conversation requires them:\n\n- **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.\n- **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.\n- **Memory architecture** (`{baseDir}/references/memory-architecture.md`): Read on first use (memory migration) and at session start (file structure, session routine, ambient capture guidelines).\n\nFile v0.3.1:_meta.json\n\n{\n  \"ownerId\": \"kn70zj1ajbxmgxbsfrw0nbtv9580p7ap\",\n  \"slug\": \"org-memory\",\n  \"version\": \"0.3.1\",\n  \"publishedAt\": 1772112963448\n}\n\nFile v0.3.1:references/knowledge-management.md\n\n# Knowledge management\n\nThis section applies when `ORG_MEMORY_USE_FOR_AGENT` is `true`. All commands operate against `$ORG_MEMORY_AGENT_DIR` and `$ORG_MEMORY_AGENT_DATABASE_LOCATION`.\n\n## Always search before creating\n\nBefore creating a node or link, check if the entity already exists:\n\n```bash\norg roam node find 'Sarah' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n```\n\n- If found: use the existing node's ID and file path\n- If not found (`headline_not_found` error): create a new node\n\n**Never create a node without searching first.** Duplicates fragment your knowledge graph.\n\n## Record an entity\n\nOnly after confirming no existing node:\n\n```bash\norg roam node create 'Sarah' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -t person -t work -f json\n```\n\n## Add structure to a node\n\nUse the file path returned by create/find commands:\n\n```bash\n# Add a headline to the node (response includes auto-assigned custom_id)\norg add <file> 'Unavailable March 2026' --tag scheduling --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n# → {\"ok\":true,\"data\":{\"custom_id\":\"k4t\",\"title\":\"Unavailable March 2026\",...}}\n\n# Use the custom_id for follow-up commands\norg note k4t 'Out all of March per human.' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n\n# Append body text to an existing headline\norg append k4t 'Confirmed by email on 2026-02-20.' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n\n# Append multi-line text via stdin\nprintf '%s' 'First paragraph.\n\nSecond paragraph.' | org append k4t --stdin -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n```\n\n**`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.\n\n**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.\n\n## Link two nodes\n\n**Always search for both nodes first** to get their IDs:\n\n```bash\n# Find source node\norg roam node find 'Bob' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n# → Returns {\"ok\":true,\"data\":{\"id\":\"e5f6a7b8-...\",\"file\":\"/path/to/bob.org\",...}}\n\n# Find target node\norg roam node find 'Alice' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n# → Returns {\"ok\":true,\"data\":{\"id\":\"a1b2c3d4-...\",...}}\n```\n\nIf either node doesn't exist, create it first. Then link using the IDs from the responses:\n\n```bash\norg roam link add <source-file> '<source-id>' '<target-id>' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" --description 'manages' -f json\n```\n\nThe `--description` is optional metadata about the relationship.\n\n## Query your knowledge\n\n```bash\n# Find a node by name\norg roam node find 'Sarah' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n\n# Read a headline's full content (body, properties, logbook)\norg read <file> 'Unavailable March 2026' -d \"$ORG_MEMORY_AGENT_DIR\" -f json\n\n# Full-text search across all indexed headlines (fast, supports boolean/prefix/phrase)\norg fts 'sarah AND march' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n\n# Regex search (slower, use when FTS isn't precise enough)\norg search 'Sarah.*March' -d \"$ORG_MEMORY_AGENT_DIR\" -f json\n\n# Browse by graph structure\norg roam backlinks 'a1b2c3d4-...' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\norg roam tag find person -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n```\n\n**`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).\n\n## Aliases and refs\n\nAliases let a node be found by multiple names. Refs associate URLs or external identifiers.\n\n```bash\norg roam alias add <file> 'a1b2c3d4-...' 'Sarah Chen' --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\"\norg roam ref add <file> 'a1b2c3d4-...' 'https://github.com/sarahchen' --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\"\n```\n\n## Node conventions\n\nUse consistent tags for easy querying:\n\n- `person` — people the human knows or works with\n- `project` — software projects, initiatives\n- `lesson` — things the agent learned the hard way\n- `preference` — how the human likes things done\n- `fact` — technical details, configuration, reference data\n\nFile v0.3.1:references/memory-architecture.md\n\n# Memory architecture\n\n`$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.\n\n**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.\n\n## Memory migration\n\nOn first use, check whether the user wants org-memory to replace OpenClaw's default memory system.\n\n1. **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.\"\n\n2. **If yes:**\n\n   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.\n\n   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.\n\n   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.\n\n   ```json\n   {\n     \"plugins\": {\n       \"slots\": {\n         \"memory\": \"none\"\n       }\n     }\n   }\n   ```\n\n   Merge this into the existing JSON — don't overwrite other keys.\n\n   d. **Sync.** Run `org roam sync` and `org index` against `$ORG_MEMORY_AGENT_DIR` so the new files are in the database.\n\n3. **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.\n\n## File structure\n\n```\n$ORG_MEMORY_AGENT_DIR/\n├── memory.org          # Curated long-term memory (read every session)\n├── daily/\n│   ├── 2026-02-21.org # Today's raw log\n│   ├── 2026-02-20.org # Yesterday's raw log\n│   └── ...\n└── *.org              # Entity nodes (people, projects, etc.)\n```\n\n**`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.\n\n**`daily/YYYY-MM-DD.org`** — raw daily logs. What happened, decisions made, ambient facts captured, things learned. Working notes, not curated. Write freely.\n\n**Entity nodes** (`*.org`) — structured roam nodes for people, projects, concepts. Tagged, linked, and queryable on demand.\n\n## Session start routine\n\nAt the start of every session:\n\n1. **Read `memory.org`** — your permanent memory, always relevant\n2. **Read today and yesterday's daily files** (`daily/YYYY-MM-DD.org`) — recent context\n3. **Load today's agenda**: `org today -d \"$ORG_MEMORY_HUMAN_DIR\" -f json`\n\nThat's it. Don't load everything. Query entity nodes on demand when the conversation needs them.\n\n## During the session\n\n- **Ambient facts** → append to today's daily file (`daily/YYYY-MM-DD.org`)\n- **New entity** → create a roam node, then link from today's daily file\n- **Update to existing entity** → `org roam node find`, then `org append` to the node\n- **Something worth keeping permanently** → also update `memory.org`\n\n## Ambient capture\n\nNot 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.\n\n**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.\n\n**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.\"\n- Cancel and reschedule: explicit requests → execute in `$ORG_MEMORY_HUMAN_DIR`\n- Sarah out all of March: ambient information → record in `$ORG_MEMORY_AGENT_DIR`\n- Do both. Don't choose one or the other.\n\n## Memory maintenance\n\nPeriodically (every few days, during a quiet moment):\n\n1. Review recent daily files\n2. Promote important facts to entity nodes or `memory.org`\n3. Remove outdated info from `memory.org`\n4. Daily files can accumulate — they're cheap and searchable via `org fts`\n\nThis 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.\n\nFile v0.3.1:references/task-management.md\n\n# Task management\n\nThis section applies when `ORG_MEMORY_USE_FOR_HUMAN` is `true`. All commands operate against `$ORG_MEMORY_HUMAN_DIR` and `$ORG_MEMORY_HUMAN_DATABASE_LOCATION`.\n\n## Read the human's state\n\n**Start here.** `org today` is the most useful query — it returns all non-done TODOs that are scheduled for today or overdue:\n\n```bash\norg today -d \"$ORG_MEMORY_HUMAN_DIR\" -f json\n```\n\nFor broader views:\n\n```bash\norg agenda today -d \"$ORG_MEMORY_HUMAN_DIR\" -f json   # all scheduled + deadlines for today\norg agenda week -d \"$ORG_MEMORY_HUMAN_DIR\" -f json    # next 7 days\norg agenda todo -d \"$ORG_MEMORY_HUMAN_DIR\" -f json    # all TODOs with scheduled dates\norg agenda todo --tag work -d \"$ORG_MEMORY_HUMAN_DIR\" -f json\n```\n\nFor rich filtering across all TODOs (scheduled or not):\n\n```bash\norg todos --state TODO -d \"$ORG_MEMORY_HUMAN_DIR\" -f json                    # all open TODOs\norg todos --state TODO --unscheduled -d \"$ORG_MEMORY_HUMAN_DIR\" -f json      # unscheduled only\norg todos --state TODO --overdue -d \"$ORG_MEMORY_HUMAN_DIR\" -f json          # overdue items\norg todos --state TODO --due-before 2026-03-01 -d \"$ORG_MEMORY_HUMAN_DIR\" -f json  # due before date\norg todos --search 'meeting' -d \"$ORG_MEMORY_HUMAN_DIR\" -f json              # search by title\norg todos --state TODO --file 'work' -d \"$ORG_MEMORY_HUMAN_DIR\" -f json      # filter by file\norg todos --state TODO --tag urgent -d \"$ORG_MEMORY_HUMAN_DIR\" -f json       # filter by tag\norg todos --state TODO --priority A -d \"$ORG_MEMORY_HUMAN_DIR\" -f json       # filter by priority\norg todos --state TODO --sort priority -d \"$ORG_MEMORY_HUMAN_DIR\" -f json    # sort by priority\norg todos --state TODO --sort scheduled --reverse -d \"$ORG_MEMORY_HUMAN_DIR\" -f json  # reverse sort\n```\n\nThe `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.\n\n## Make changes\n\n```bash\n# Add a headline (response includes the auto-assigned custom_id)\norg 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\n\n# Subsequent commands use the custom_id — no file path needed\norg todo k4t DONE -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg schedule a1b 2026-03-15 -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg note a1b 'Pushed back per manager request' -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\"\norg append a1b 'Meeting notes from standup.' -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\n\n# Refile still requires explicit file paths\norg 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\n```\n\n## Preview before writing\n\nUse `--dry-run` to see what a mutation would produce without modifying the file:\n\n```bash\norg todo tasks.org 'Buy groceries' DONE --dry-run -f json\n```\n\n## Batch operations\n\nApply multiple mutations atomically. Commands execute sequentially against in-memory state. Files are written only if all succeed.\n\n```bash\necho '{\"commands\":[\n  {\"command\":\"todo\",\"file\":\"tasks.org\",\"identifier\":\"Buy groceries\",\"args\":{\"state\":\"DONE\"}},\n  {\"command\":\"tag-add\",\"file\":\"tasks.org\",\"identifier\":\"Write report\",\"args\":{\"tag\":\"urgent\"}},\n  {\"command\":\"schedule\",\"file\":\"tasks.org\",\"identifier\":\"Write report\",\"args\":{\"date\":\"2026-03-01\"}},\n  {\"command\":\"append\",\"file\":\"tasks.org\",\"identifier\":\"Write report\",\"args\":{\"text\":\"Include Q1 metrics.\"}}\n]}' | org batch -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\n```\n\n## Query shortcuts\n\nWhen 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.\n\n| Human says | Action |\n|---|---|\n| \"What do I need to do?\" / \"What's on my plate?\" | `org today -d \"$ORG_MEMORY_HUMAN_DIR\" -f json` (today + overdue) |\n| \"What's overdue?\" | `org todos --state TODO --overdue -d \"$ORG_MEMORY_HUMAN_DIR\" -f json` |\n| \"What's coming up this week?\" | `org agenda week -d \"$ORG_MEMORY_HUMAN_DIR\" -f json` |\n| \"Show me everything tagged work\" | `org todos --state TODO --tag work -d \"$ORG_MEMORY_HUMAN_DIR\" -f json` |\n| \"What do I have unscheduled?\" | `org todos --state TODO --unscheduled -d \"$ORG_MEMORY_HUMAN_DIR\" -f json` |\n| \"Find all tasks about X\" | `org todos --search 'X' -d \"$ORG_MEMORY_HUMAN_DIR\" -f json` |\n| \"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) |\n| \"What's the status of project X?\" | `org fts 'X' -d \"$ORG_MEMORY_AGENT_DIR\"` + `org todos --search 'X' -d \"$ORG_MEMORY_HUMAN_DIR\"` |\n| \"Search my notes for Y\" | `org fts 'Y' -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json` |\n\nPresent results in a clean, readable format. Don't dump raw JSON at the human — summarise it.\n\nArchive v0.2.1: 3 files, 7269 bytes\n\nFiles: README.md (5186b), SKILL.md (12999b), _meta.json (129b)\n\nFile v0.2.1:SKILL.md\n\n---\nname: org-memory\ndescription: \"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.\"\nmetadata: {\"openclaw\":{\"emoji\":\"🦄\",\"requires\":{\"bins\":[\"org\"]},\"install\":[{\"id\":\"github-release\",\"kind\":\"manual\",\"label\":\"Download from GitHub releases: https://github.com/dcprevere/org-cli/releases\"}]}}\n---\n\n# org-memory\n\nUse 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.\n\n## Shortcuts\n\nWhen your human uses these patterns, act immediately:\n\n| Pattern | Action |\n|---------|--------|\n| `Remember: <info>` | Save to your knowledge base (`$ORG_MEMORY_AGENT_DIR`). Create or update a node. This is for *your* future recall. |\n| `Note: <task or info>` | Add to the human's org files (`$ORG_MEMORY_HUMAN_DIR/inbox.org`). This is for *them* to act on. |\n\nExamples:\n- \"Remember: Sarah prefers morning meetings\" → Create/update a node for Sarah in your repo\n- \"Note: Buy groceries\" → Add a TODO to the human's inbox\n- \"Remember: The API uses OAuth2, not API keys\" → Create/update a node for the API in your repo\n- \"Note: Review PR #42 by Friday\" → Add a TODO with deadline to the human's inbox\n\nDon't ask for confirmation on shortcuts — just do it. After every write, print a line in this exact format:\n\n```\norg-memory: <action> <file-path>\n```\n\nExamples: `org-memory: added TODO to ~/org/human/inbox.org`, `org-memory: created node ~/org/agent/sarah.org`, `org-memory: updated ~/org/agent/sarah.org`.\n\n## Output format\n\nAll commands accept `-f json` for structured output with `{\"ok\":true,\"data\":...}` envelopes. Errors return `{\"ok\":false,\"error\":{\"type\":\"...\",\"message\":\"...\"}}`. Always use `-f json`.\n\n## Discovery\n\nRun `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.\n\n## Setup\n\nConfiguration is via environment variables. Set them in `openclaw.json` so they are injected into every command automatically.\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `ORG_MEMORY_USE_FOR_AGENT` | `true` | Enable the agent's own knowledge base |\n| `ORG_MEMORY_AGENT_DIR` | `~/org/agent` | Agent's org directory |\n| `ORG_MEMORY_AGENT_DATABASE_LOCATION` | `~/.local/share/org-memory/agent/.org.db` | Agent's database |\n| `ORG_MEMORY_USE_FOR_HUMAN` | `true` | Enable task management in the human's org files |\n| `ORG_MEMORY_HUMAN_DIR` | `~/org/human` | Human's org directory |\n| `ORG_MEMORY_HUMAN_DATABASE_LOCATION` | `~/.local/share/org-memory/human/.org.db` | Human's database |\n\nIf `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.\n\nAlways 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.\n\nInitialize each enabled directory by creating a first node and building the headline index:\n\n```bash\norg roam node create \"Index\" -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\norg index -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\"\norg index -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\"\n```\n\nThe roam response includes the node's ID, file path, title, and tags. The index enables CUSTOM_ID auto-assignment and file-less commands.\n\n## Knowledge management\n\nThis section applies when `ORG_MEMORY_USE_FOR_AGENT` is `true`.\n\n### ⚠️ Always search before creating\n\nBefore creating a node or link, check if the entity already exists:\n\n```bash\norg roam node find \"Sarah\" -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n```\n\n- If found: use the existing node's ID and file path\n- If not found (`headline_not_found` error): create a new node\n\n**Never create a node without searching first.** Duplicates fragment your knowledge graph.\n\n### Record an entity\n\nOnly after confirming no existing node:\n\n```bash\norg roam node create \"Sarah\" -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -t person -t work -f json\n```\n\n### Add structure to a node\n\nUse the file path returned by create/find commands:\n\n```bash\n# Add a headline to the node (response includes auto-assigned custom_id)\norg add <file> \"Unavailable March 2026\" --tag scheduling --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n# → {\"ok\":true,\"data\":{\"custom_id\":\"k4t\",\"title\":\"Unavailable March 2026\",...}}\n\n# Use the custom_id for follow-up commands\norg note k4t \"Out all of March per human.\" -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n\n# Append body text to an existing headline\norg append k4t \"Confirmed by email on 2026-02-20.\" -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n\n# Append multi-line text via stdin\necho \"First paragraph.\\n\\nSecond paragraph.\" | org append k4t --stdin -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n```\n\n**`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.\n\n**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.\n\n### Link two nodes\n\n**Always search for both nodes first** to get their IDs:\n\n```bash\n# Find source node\norg roam node find \"Bob\" -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n# → Returns {\"ok\":true,\"data\":{\"id\":\"e5f6a7b8-...\",\"file\":\"/path/to/bob.org\",...}}\n\n# Find target node  \norg roam node find \"Alice\" -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n# → Returns {\"ok\":true,\"data\":{\"id\":\"a1b2c3d4-...\",...}}\n```\n\nIf either node doesn't exist, create it first. Then link using the IDs from the responses:\n\n```bash\norg roam link add <source-file> \"<source-id>\" \"<target-id>\" -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" --description \"manages\" -f json\n```\n\nThe `--description` is optional metadata about the relationship.\n\n### Query your knowledge\n\n```bash\norg roam node find \"Sarah\" -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\norg roam backlinks \"a1b2c3d4-...\" -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\norg roam tag find person -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\norg search \"Sarah.*March\" -d \"$ORG_MEMORY_AGENT_DIR\" -f json\n```\n\n### Add aliases and refs\n\nAliases let a node be found by multiple names. Refs associate URLs or external identifiers.\n\n```bash\norg roam alias add <file> \"a1b2c3d4-...\" \"Sarah Chen\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\"\norg roam ref add <file> \"a1b2c3d4-...\" \"https://github.com/sarahchen\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\"\n```\n\n## Task management\n\nThis section applies when `ORG_MEMORY_USE_FOR_HUMAN` is `true`.\n\n### Read the human's state\n\n**Start here.** `org today` is the most useful query — it returns all non-done TODOs that are scheduled for today or overdue:\n\n```bash\norg today -d \"$ORG_MEMORY_HUMAN_DIR\" -f json\n```\n\nFor broader views:\n\n```bash\norg agenda today -d \"$ORG_MEMORY_HUMAN_DIR\" -f json   # all scheduled + deadlines for today\norg agenda week -d \"$ORG_MEMORY_HUMAN_DIR\" -f json    # next 7 days\norg agenda todo -d \"$ORG_MEMORY_HUMAN_DIR\" -f json    # all TODOs\norg agenda todo --tag work -d \"$ORG_MEMORY_HUMAN_DIR\" -f json\n```\n\n### Make changes\n\n```bash\n# Add a headline (response includes the auto-assigned custom_id)\norg 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\n\n# Subsequent commands use the custom_id — no file path needed\norg todo k4t DONE -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg schedule a1b 2026-03-15 -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg note a1b \"Pushed back per manager request\" -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\"\norg append a1b \"Meeting notes from standup.\" -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\n\n# Refile still requires explicit file paths\norg 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\n```\n\n### Preview before writing\n\nUse `--dry-run` to see what a mutation would produce without modifying the file:\n\n```bash\norg todo tasks.org \"Buy groceries\" DONE --dry-run -f json\n```\n\n## Batch operations\n\nThis section applies when `ORG_MEMORY_USE_FOR_HUMAN` is `true`.\n\nApply multiple mutations atomically. Commands execute sequentially against in-memory state. Files are written only if all succeed.\n\n```bash\necho '{\"commands\":[\n  {\"command\":\"todo\",\"file\":\"tasks.org\",\"identifier\":\"Buy groceries\",\"args\":{\"state\":\"DONE\"}},\n  {\"command\":\"tag-add\",\"file\":\"tasks.org\",\"identifier\":\"Write report\",\"args\":{\"tag\":\"urgent\"}},\n  {\"command\":\"schedule\",\"file\":\"tasks.org\",\"identifier\":\"Write report\",\"args\":{\"date\":\"2026-03-01\"}},\n  {\"command\":\"append\",\"file\":\"tasks.org\",\"identifier\":\"Write report\",\"args\":{\"text\":\"Include Q1 metrics.\"}}\n]}' | org batch -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\n```\n\n## When to record knowledge\n\nWhen 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`.\n\nExample: \"Cancel my Thursday meeting with Sarah and reschedule the API migration review to next week. Sarah is going to be out all of March.\"\n\n- Cancel and reschedule: explicit requests, execute in `$ORG_MEMORY_HUMAN_DIR`\n- Sarah out all of March: ambient information, record in `$ORG_MEMORY_AGENT_DIR`\n\nIf 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.\n\nCheck whether a node already exists before creating it. Use the returned data from mutations rather than making follow-up queries.\n\n**Always report writes.** After every mutation to either directory, print `org-memory: <action> <file-path>`. Never silently write to either directory.\n\n## Stable identifiers (CUSTOM_ID)\n\nEvery 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.\n\nUse CUSTOM_IDs to refer to headlines in subsequent commands — they are stable across edits and don't require a file path:\n\n```bash\norg todo k4t DONE -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg schedule k4t 2026-03-15 -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg note k4t \"Pushed back per manager request\" -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg append k4t \"Updated scope per review.\" -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\n```\n\nTo backfill CUSTOM_IDs on existing headlines that don't have them:\n\n```bash\norg custom-id assign -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\"\n```\n\nNever address headlines by position number. Positions change when files are edited. Use CUSTOM_ID, org-id, or exact title.\n\n## Error handling\n\nBranch on the `ok` field. Handle errors by `type`:\n\n- `file_not_found`: wrong path or deleted file\n- `headline_not_found`: identifier doesn't match; re-query to get current state\n- `parse_error`: file has syntax the parser can't handle; don't retry\n- `invalid_args`: check `org schema` or `org <command> --help`\n\n## Troubleshooting\n\n### Duplicate nodes created\nYou didn't search before creating. Always run `node find` first. If duplicates exist, manually delete the newer file and run `org roam sync`.\n\n### \"headline_not_found\" when using org note\nYou 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.\n\n### Links show wrong display text\nThe `--description` parameter sets relationship metadata, not display text. The link displays the target node's title. This is correct org-roam behavior.\n\n### Database out of sync\nRun `org roam sync -d <dir> --db <db-path>` to rebuild the database from files.\n\nFile v0.2.1:README.md\n\n# org-memory\n\nAn [OpenClaw](https://github.com/openclaw/openclaw) skill that gives your agent structured, linked, human-readable memory using org-mode files.\n\n## Install\n\n1. Put `org` on your PATH ([releases](https://github.com/dcprevere/org-cli/releases)).\n\n2. Copy the skill into your OpenClaw skills directory:\n\n```sh\ncp -r integrations/openclaw ~/.openclaw/skills/org-memory\n```\n\n3. Ask your agent to \"refresh skills\" or restart the gateway.\n\n## Quick start\n\nOnce installed, just talk to your agent naturally:\n\n- **\"Remember: Sarah prefers morning meetings\"** → Agent saves to its knowledge base\n- **\"Note: Buy groceries\"** → Agent adds TODO to your inbox\n- **\"What do you know about Sarah?\"** → Agent queries its knowledge\n\n## When to use org-memory\n\nOpenClaw's default memory (`MEMORY.md` + semantic search) works well for simple setups. org-memory is worth the added complexity when you need more.\n\n### org-memory vs MEMORY.md\n\n| Capability | MEMORY.md | org-memory |\n|------------|-----------|------------|\n| Store facts about one person | Works great | Overkill |\n| Store 20+ entities (people, projects, companies) | Gets messy | Each entity = separate file |\n| \"List all my clients\" | Grep through text | `tag find client` → structured list |\n| Track relationships | Text references | Graph links with backlinks |\n| \"What do I need to do today?\" | Not possible | `org today` → due + overdue TODOs |\n| \"What's due this week?\" | Not possible | `agenda week` → parsed dates |\n| Task management | No date support | SCHEDULED, DEADLINE, repeaters |\n| \"Mark that task done\" | Find file, find line | `org todo k4t DONE` |\n\n**Use MEMORY.md** for: personal preferences, key dates, simple facts (<100 items).\n\n**Use org-memory** for: CRM-like knowledge, task management, relationship graphs, or any knowledge base that will grow beyond 100 entities.\n\n### org-memory vs Obsidian\n\nBoth are linked knowledge graphs. Key differences:\n\n| | Obsidian | org-memory |\n|---|----------|------------|\n| Format | Markdown + YAML frontmatter | Org-mode |\n| Task management | Limited (no native dates) | Full agenda: SCHEDULED, DEADLINE, repeaters, clock |\n| Query language | Dataview plugin (JS-based) | CLI with JSON output |\n| Human editing | Obsidian app or any editor | Emacs or any editor |\n| Agent integration | Needs custom tooling | Built for CLI/agent use |\n\n**Use Obsidian** if: you already live in Obsidian and want your agent to share that vault.\n\n**Use org-memory** if: you need real task management with dates, prefer CLI-native tooling, or use Emacs.\n\n### The killer feature\n\nThe real differentiator is **agenda queries** and **short IDs**. The moment you want:\n- \"What's due today?\" → `org today` shows all non-done TODOs due today or overdue\n- \"Schedule this for next Monday\"\n- \"Show me overdue tasks\" → `org today` catches these automatically\n- \"Mark k4t as done\" (no file path needed)\n\n...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.\n\n## What it does\n\nThe skill teaches the agent to use `org` for:\n\n- **Knowledge graph**: create nodes, link them, query by tag/title/backlink/search\n- **Task management**: create/complete/schedule/refile tasks in the human's org files\n- **Structured memory**: record entities, relationships, and constraints as linked org-roam nodes instead of flat text\n- **Batch mutations**: apply multiple changes atomically\n\nBy 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.\n\n## Configuration\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `ORG_MEMORY_USE_FOR_AGENT` | `true` | Enable the agent's own knowledge base |\n| `ORG_MEMORY_AGENT_DIR` | `~/org/agent` | Agent's org directory |\n| `ORG_MEMORY_AGENT_DATABASE_LOCATION` | `~/.local/share/org-memory/agent/.org.db` | Agent's database |\n| `ORG_MEMORY_USE_FOR_HUMAN` | `true` | Enable task management in the human's org files |\n| `ORG_MEMORY_HUMAN_DIR` | `~/org/human` | Human's org directory |\n| `ORG_MEMORY_HUMAN_DATABASE_LOCATION` | `~/.local/share/org-memory/human/.org.db` | Human's database |\n\nAll 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.\n\nThe 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`.\n\nTo override, set them in `~/.openclaw/openclaw.json`:\n\n```json\n{\n  \"skills\": {\n    \"entries\": {\n      \"org-memory\": {\n        \"env\": {\n          \"ORG_MEMORY_USE_FOR_HUMAN\": \"false\",\n          \"ORG_MEMORY_AGENT_DIR\": \"/path/to/agent\",\n          \"ORG_MEMORY_AGENT_DATABASE_LOCATION\": \"/path/to/agent.db\"\n        }\n      }\n    }\n  }\n}\n```\n\nOr export them in your shell. Shell env takes precedence over `openclaw.json`.\n\nFile v0.2.1:_meta.json\n\n{\n  \"ownerId\": \"kn70zj1ajbxmgxbsfrw0nbtv9580p7ap\",\n  \"slug\": \"org-memory\",\n  \"version\": \"0.2.1\",\n  \"publishedAt\": 1771600262202\n}","readmeExcerpt":"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. - Clarifi","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"org-memory: <action> <file-path>"},{"language":"bash","snippet":"# Correct\norg add \"$ORG_MEMORY_HUMAN_DIR/inbox.org\" 'User provided text' --todo TODO -f json\n\n# Wrong — double quotes allow shell injection\norg add \"$ORG_MEMORY_HUMAN_DIR/inbox.org\" \"User provided text\" --todo TODO -f json"},{"language":"bash","snippet":"org add \"$ORG_MEMORY_HUMAN_DIR/inbox.org\" 'Don'\\''t forget' --todo TODO -f json"},{"language":"bash","snippet":"printf '%s' 'Long text here' | org append k4t --stdin -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json"},{"language":"bash","snippet":"# Sync existing files into the roam database (skip if starting fresh)\norg roam sync -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\"\norg roam sync -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\"\n\n# Create a seed node for the agent's knowledge base (skip if files already exist)\norg roam node create 'Index' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n\n# Build the headline index (enables CUSTOM_ID auto-assignment and file-less commands)\norg index -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\"\norg index -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\""},{"language":"bash","snippet":"org todo k4t DONE -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg schedule k4t 2026-03-15 -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg note k4t 'Pushed back per manager request' -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg append k4t 'Updated scope per review.' -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: org-memory\nversion: 0.3.0\ndescription: \"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.\"\nmetadata: {\"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\"}]}}\n---\n\n# org-memory\n\nUse 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.\n\n## Shortcuts\n\nWhen your human uses these patterns, act on them directly.\n\n| Keyword | Meaning | Target |\n|---|---|---|\n| `Todo:` | Create a task with a date | `$ORG_MEMORY_HUMAN_DIR` |\n| `Note:` | Write this down for me | `$ORG_MEMORY_HUMAN_DIR` |\n| `Done:` / `Finished:` | Mark a task complete | `$ORG_MEMORY_HUMAN_DIR` |\n| `Know:` | Store this for agent recall | `$ORG_MEMORY_AGENT_DIR` |\n\n### Todo — create a task\n\n`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>`.\n\nAction: `org add \"$ORG_MEMORY_HUMAN_DIR/inbox.org\" '<title>' --todo TODO --scheduled <date> --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json`\n\nUse `--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\").\n\nExamples:\n- \"Todo: submit taxes in 3 weeks\" → `org add .../inbox.org 'Submit taxes' --todo TODO --scheduled 2026-03-18`\n- \"Todo: renew passport by June\" → `org add .../inbox.org 'Renew passport' --todo TODO --deadline 2026-06-01`\n- \"Todo: call dentist tomorrow\" → `org add .../inbox.org 'Call dentist' --todo TODO --scheduled 2026-02-26`\n- \"Todo: book flights\" → `org add .../inbox.org 'Book flights' --todo TODO` (no date mentioned)\n\n### Note — for the human\n\n`Note: <text>` means \"add this to MY org files.\" It is always a task or reminder for the *human*, not for the agent.\n\nAction: `org add \"$ORG_MEMORY_HUMAN_DIR/inbox.org\" '<text>' --todo TODO -f json`\n\nIf 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).\n\nExamples:\n- \"Note: Buy groceries\" → `org add .../inbox.org 'Buy groceries' --todo TODO`\n- \"Note: Review PR #42 by Friday\" → `org add .../inbox.org 'Review PR #42' --todo TODO --deadline 2026-02-28`\n- \"Note: we could add feature X to the app\" → `org add .../inbox.org 'A"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn70zj1ajbxmgxbsfrw0nbtv9580p7ap\",\n  \"slug\": \"org-memory\",\n  \"version\": \"0.3.1\",\n  \"publishedAt\": 1772112963448\n}"},{"path":"references/knowledge-management.md","content":"# Knowledge management\n\nThis section applies when `ORG_MEMORY_USE_FOR_AGENT` is `true`. All commands operate against `$ORG_MEMORY_AGENT_DIR` and `$ORG_MEMORY_AGENT_DATABASE_LOCATION`.\n\n## Always search before creating\n\nBefore creating a node or link, check if the entity already exists:\n\n```bash\norg roam node find 'Sarah' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n```\n\n- If found: use the existing node's ID and file path\n- If not found (`headline_not_found` error): create a new node\n\n**Never create a node without searching first.** Duplicates fragment your knowledge graph.\n\n## Record an entity\n\nOnly after confirming no existing node:\n\n```bash\norg roam node create 'Sarah' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -t person -t work -f json\n```\n\n## Add structure to a node\n\nUse the file path returned by create/find commands:\n\n```bash\n# Add a headline to the node (response includes auto-assigned custom_id)\norg add <file> 'Unavailable March 2026' --tag scheduling --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n# → {\"ok\":true,\"data\":{\"custom_id\":\"k4t\",\"title\":\"Unavailable March 2026\",...}}\n\n# Use the custom_id for follow-up commands\norg note k4t 'Out all of March per human.' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n\n# Append body text to an existing headline\norg append k4t 'Confirmed by email on 2026-02-20.' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n\n# Append multi-line text via stdin\nprintf '%s' 'First paragraph.\n\nSecond paragraph.' | org append k4t --stdin -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n```\n\n**`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.\n\n**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.\n\n## Link two nodes\n\n**Always search for both nodes first** to get their IDs:\n\n```bash\n# Find source node\norg roam node find 'Bob' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n# → Returns {\"ok\":true,\"data\":{\"id\":\"e5f6a7b8-...\",\"file\":\"/path/to/bob.org\",...}}\n\n# Find target node\norg roam node find 'Alice' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" -f json\n# → Returns {\"ok\":true,\"data\":{\"id\":\"a1b2c3d4-...\",...}}\n```\n\nIf either node doesn't exist, create it first. Then link using the IDs from the responses:\n\n```bash\norg roam link add <source-file> '<source-id>' '<target-id>' -d \"$ORG_MEMORY_AGENT_DIR\" --db \"$ORG_MEMORY_AGENT_DATABASE_LOCATION\" --description 'manages' -f json\n```\n\nThe `--description` is optional metadata about the relationship.\n\n## Query your knowledge\n\n```bash\n# Find a node by name\norg roam node find 'Sarah' "},{"path":"references/memory-architecture.md","content":"# Memory architecture\n\n`$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.\n\n**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.\n\n## Memory migration\n\nOn first use, check whether the user wants org-memory to replace OpenClaw's default memory system.\n\n1. **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.\"\n\n2. **If yes:**\n\n   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.\n\n   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.\n\n   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.\n\n   ```json\n   {\n     \"plugins\": {\n       \"slots\": {\n         \"memory\": \"none\"\n       }\n     }\n   }\n   ```\n\n   Merge this into the existing JSON — don't overwrite other keys.\n\n   d. **Sync.** Run `org roam sync` and `org index` against `$ORG_MEMORY_AGENT_DIR` so the new files are in the database.\n\n3. **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.\n\n## File structure\n\n```\n$ORG_MEMORY_AGENT_DIR/\n├── memory.org          # Curated long-term memory (read every session)\n├── daily/\n│   ├── 2026-02-21.org # Today's raw log\n│   ├── 2026-02-20.org # Yesterday's raw log\n│   └── ...\n└── *.org              # Entity nodes (people, projects, etc.)\n```\n\n**`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.\n\n**`daily/YYYY-MM-DD.org`** — raw daily logs. What happened, decisions made, ambient facts captured, things learned. Working notes, not curated. Write freely.\n\n**Entity nodes** (`*.org`) — structured roam nodes for people, projects, concepts. Tagged, l"},{"path":"references/task-management.md","content":"# Task management\n\nThis section applies when `ORG_MEMORY_USE_FOR_HUMAN` is `true`. All commands operate against `$ORG_MEMORY_HUMAN_DIR` and `$ORG_MEMORY_HUMAN_DATABASE_LOCATION`.\n\n## Read the human's state\n\n**Start here.** `org today` is the most useful query — it returns all non-done TODOs that are scheduled for today or overdue:\n\n```bash\norg today -d \"$ORG_MEMORY_HUMAN_DIR\" -f json\n```\n\nFor broader views:\n\n```bash\norg agenda today -d \"$ORG_MEMORY_HUMAN_DIR\" -f json   # all scheduled + deadlines for today\norg agenda week -d \"$ORG_MEMORY_HUMAN_DIR\" -f json    # next 7 days\norg agenda todo -d \"$ORG_MEMORY_HUMAN_DIR\" -f json    # all TODOs with scheduled dates\norg agenda todo --tag work -d \"$ORG_MEMORY_HUMAN_DIR\" -f json\n```\n\nFor rich filtering across all TODOs (scheduled or not):\n\n```bash\norg todos --state TODO -d \"$ORG_MEMORY_HUMAN_DIR\" -f json                    # all open TODOs\norg todos --state TODO --unscheduled -d \"$ORG_MEMORY_HUMAN_DIR\" -f json      # unscheduled only\norg todos --state TODO --overdue -d \"$ORG_MEMORY_HUMAN_DIR\" -f json          # overdue items\norg todos --state TODO --due-before 2026-03-01 -d \"$ORG_MEMORY_HUMAN_DIR\" -f json  # due before date\norg todos --search 'meeting' -d \"$ORG_MEMORY_HUMAN_DIR\" -f json              # search by title\norg todos --state TODO --file 'work' -d \"$ORG_MEMORY_HUMAN_DIR\" -f json      # filter by file\norg todos --state TODO --tag urgent -d \"$ORG_MEMORY_HUMAN_DIR\" -f json       # filter by tag\norg todos --state TODO --priority A -d \"$ORG_MEMORY_HUMAN_DIR\" -f json       # filter by priority\norg todos --state TODO --sort priority -d \"$ORG_MEMORY_HUMAN_DIR\" -f json    # sort by priority\norg todos --state TODO --sort scheduled --reverse -d \"$ORG_MEMORY_HUMAN_DIR\" -f json  # reverse sort\n```\n\nThe `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.\n\n## Make changes\n\n```bash\n# Add a headline (response includes the auto-assigned custom_id)\norg 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\n\n# Subsequent commands use the custom_id — no file path needed\norg todo k4t DONE -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg schedule a1b 2026-03-15 -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\norg note a1b 'Pushed back per manager request' -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\"\norg append a1b 'Meeting notes from standup.' -d \"$ORG_MEMORY_HUMAN_DIR\" --db \"$ORG_MEMORY_HUMAN_DATABASE_LOCATION\" -f json\n\n# Refile still requires explicit file paths\norg 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\n```\n\n## Preview before writing\n\nUse `--dry-run` to see what a mutation would produce withou"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1777,"uniquenessScore":38,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-04-17T06:14:54.483Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}