Temporal Memory | ONDE Docs

Goal

Keep repo clean. Scale without chaos. Idempotent ops. Safe automation.

8.1 Organize & Format (`onde organize`)

Your graph gofmt. Normalizes property order, sorts nodes, adds grouping, cleans whitespace. Zero data loss. Only structure changes.

onde organize                     # format whole workspace
onde organize tasks/active.md     # format single file
onde organize --dry-run           # preview changes
onde organize --watch             # auto-format on save

What it fixes:

Property order → matches schema declaration (or alphabetical if schemaless)
Blank lines → normalized to one between nodes
Trailing whitespace → stripped
Node order → respects @sort or CLI flags
Group headers → inserts by status:: BLOCKED etc. when --group-by used

Rule: Run before commit. Keeps diffs clean. Safe to run repeatedly.

8.2 Split & Merge

Files grow messy. Split fat files. Merge scattered files.

Split: One File → Many

onde organize tasks/active.md --split
onde organize tasks/active.md --split --into tasks/
onde organize tasks/active.md --split --naming "{id}.md"
onde organize tasks/active.md --split --batch-size 30    # paginate: 30 nodes per file

Each node becomes its own file. Links stay intact. IDs resolve regardless of filename. --batch-size keeps dense format, splits into *.batch-NN.md files.

Auto-split: Set @max-rows + @auto-split in schema → onde lint auto-paginates. No manual --split needed. → Schema Evolution §5.7a

Merge: Many Files → One

onde organize --type task --merge --output tasks/overview.md
onde organize --type task --merge --format dense --output tasks/overview.md
onde organize --type task --merge --remove-sources   # deletes originals after merge

Creates combined file. Groups/sorts applied. Source files kept by default (add --remove-sources to delete).

Rule: Split for deep work. Merge for dashboards. Always --dry-run first.

8.3 Move & Rename

Match schema directory rules. Fix naming drift. Safe path updates.

onde organize --dirs              # move files to match schema dirs
onde organize --rename            # rename files to match @naming rules
onde organize --dirs --dry-run    # preview moves

Before:

random/fix-auth.md   (type:: task)
people/Tom.md        (type:: person)

After (onde organize --dirs --rename):

tasks/task-882.md
people/tom-walker.md

Rule: Convert path links to ID links first. onde relink --to id → then move/rename. Zero broken links.

8.4 Relink & Audit (`onde relink`)

Convert link styles workspace-wide. Audit distribution. Fix ambiguity.

onde relink --to id               # all links → [[task-882]]
onde relink --to title            # all links → [[Fix token refresh]]
onde relink --to path             # all links → [[/tasks/task-882.md]]
onde relink --to relative         # all links → [[./task-882.md]]
onde relink --audit               # stats only, zero changes
onde relink --dry-run             # preview

Scope flags: --scope file, --scope directory, --scope type. Target specific areas.

Rule: ID links = stable. Title links = human-friendly. Path links = break on move. Pick one style. Enforce with relink.

8.5 Workspace Health (`onde tree`)

See structure. Track token budgets. Spot bloat.

onde tree                         # full workspace tree
onde tree tasks/                  # specific dir
onde tree --by type               # group by node type
onde tree --over-budget           # show files/dirs exceeding budget
onde tree --depth 2               # limit depth

Output shows:

Directory structure
File count per dir
Token count per file/dir
Over-budget flags (OVER:)

Rule: Run weekly. Trim fat files. Archive stale dirs. Raise budgets only when growth is legitimate.

8.6 Rebuild & Recover (`onde materialize`)

Markdown gets messy? Deleted by mistake? Rebuild from truth.

onde materialize                  # rebuild all MD
onde materialize --type task      # rebuild only task files
onde materialize --dry-run        # preview
onde materialize --check          # verify MD matches truth (no writes)

What it does:

Reads current graph state
Applies schema rules (dirs, naming, format, sort, group)
Writes clean markdown files
Skips unchanged files (incremental)

Rule: MD = view. Truth lives in journal. Delete MD anytime. onde materialize recovers it. Zero panic.

8.7 Daily Hygiene Workflow

Edit freely
│
▼
onde lint                         # sync + validate + auto-fix
│
▼
onde organize                     # format + sort + group
│
▼
onde tree --over-budget           # check health (weekly)
│
▼
onde git commit                   # lock state

Idempotent guarantee: Run onde organize twice. Same result. Hash-based skip. Safe for CI, cron, pre-commit hooks. Never drifts. Never duplicates work.

Common Traps & Fixes

Trap	Symptom	Fix
Broken links after move	`[[/old/path.md]]` fails	`onde relink --to id` before moving
Merge overwrites file	`--output` exists	Add `--force` or pick new name
Organize changes nothing	File already clean	Idempotent. Expected. Skip commit.
`--remove-sources` deletes wrong files	Used without `--merge`	Flag ignored unless `--merge` active. Always `--dry-run`.
Tree shows no budgets	Schema has no `@max-*`	Stats still print. Add budgets to schema when ready.
Materialize feels slow	Full rebuild on large workspace	Use `--type X` or fix lint state. Incremental is fast.

Next Step: → Multi-User, Git & Collaboration