box-write

name	box-write
description	Save a memory to the local Box Drive workspace as a markdown file with YAML frontmatter and Obsidian-style wikilinks. Append-only - never overwrites. FS-only - no Box API calls; no metadata template instance application. Use when the user says remember, save, log a decision, record an observation, or note that something happened.
argument-hint	[content] [--kind=<kind>] [--title=<title>] [--team=<team>] [--tags=<a,b,c>]

/box-write

If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.

Commit a memory to the local Box Drive workspace. Box Drive syncs it to Box cloud asynchronously; from the agent's perspective the operation completes at the local FS write.

Usage

/box-write [content] [--kind=<kind>] [--title=<title>] [--team=<team>] [--tags=<a,b,c>]

Examples:

• /box-write We decided to use JWT instead of sessions because of mobile. — saves a decision (kind inferred)
• /box-write --kind=task --title="Rotate keys" --tags=ops,security Cron monthly

What to do

1. Verify workspace. Read _box-memory.json. If missing, run box-init first.
2. Verify backend. Confirm box-drive-detect shows mount writable + Box Drive running. If not, error and stop.
3. Generate IDs. ULID prefixed mem_ (timestamp + random; lex-sortable). Slug = kebab-case from title (lowercase, alphanumeric + hyphens only).
4. Determine kind. decision | fact | task | observation | reference | note | companion. Infer from content if not provided.
5. Slug collision check. Read target folder's _index.json. If existing active memory has same slug:
   • Same concept → supersede (set old → status: superseded, superseded_by: <new_id>)
   • Different concept → append -2 (or -3, etc.) to slug
6. Build frontmatter. Fields: id, slug, title, kind, status (default active), team, agent, created_at, updated_at, tags, related (wikilinks as double-quoted strings), links, supersedes (if applicable). ASCII only (no em-dashes, no smart quotes).
7. Compose body. Markdown with H1 title, brief callout, context, kind-specific section, related wikilinks. Obsidian-style [[Title]] for cross-memory references.
8. Determine target folder.
   • Default: <workspace>/memories/
   • With --team=<name>: <workspace>/teams/<name>/memories/
9. Acquire workspace lock (see lockfile protocol in box-init SKILL.md). Required because we're about to update an index.
10. Write the memory file atomically: <filename>.tmp → fsync → rename. Filename: <kind>__<slug>.md (double underscore).
11. Compute SHA256 of the file body locally (not for companion-style anchoring; this just goes in the index for integrity later).
12. Update folder's _index.json. Append the new entry; update all inverted maps (by_id, by_slug, by_wikilink, by_kind, by_status, by_tag). Set file_id: null (Box assigns later; the on-prem variant doesn't fill it). local_path is the relative path from workspace root.
13. Release lock.
14. Report. Title, mem ID, file path (relative), tags, related links, supersession info. Note that Box Drive will sync on its own schedule — local write is complete.

Frontmatter shape (compatible with cloud variant's schema)

---
id: mem_01HXYZ...                  # ULID
slug: jwt-vs-sessions-decision     # kebab-case
title: JWT vs Sessions Decision    # plain English
kind: decision                     # decision | fact | task | observation | reference | note
status: active                     # active | draft | superseded | archived | held
team: default
agent: box-memory-onprem           # this plugin's identifier
created_at: 2026-05-24T18:14:00Z
updated_at: 2026-05-24T18:14:00Z
tags: [auth, mobile, security]
related:
  - "[[Login Flow]]"
  - "[[Session Management]]"
links:
  - { url: "ref-link-here", label: "RFC 7519 (JWT)" }
---

Quality bar

• Title is searchable — real words a human would type, not internal jargon
• Body explains WHY, not just WHAT
• Tags sparse — 2-5 per memory
• Wikilinks intentional — only link to memories you've verified exist or are about to write

When NOT to write

• Conversational acknowledgments ("got it", "thanks")
• Recap of code already in git
• Time-bound trivia
• Content the user said don't save

Differences from cloud variant

• No metadata template instance application — local FS can't apply Box metadata; that's a Box API operation
• file_id is null in the index (Box assigns IDs on cloud upload, not before)
• No instant cross-machine recall — depends on Box Drive sync latency (typically seconds-minutes)
• No URL link to Box file — until Box Drive syncs, the file only exists locally

If the user needs any of those features for this specific memory, they should run the cloud variant for this write. Both plugins write to the same workspace shape; an entry written by one is readable by the other (with file_id filled in by the cloud variant on its first read of the file after sync).

Errors

• No workspace → run box-init first
• Lock cannot be acquired → another writer is active or a stale lock exists; suggest box-index-rebuild to inspect
• Mount lost mid-write (e.g., Box Drive crashed) → write may be incomplete; surface clearly so user can investigate

Don't

• Don't overwrite memory files. Always create-new or supersede.
• Don't skip the index update — recall depends on it.
• Don't fabricate wikilink targets that don't exist.
• Don't call any Box API. Don't read any URL. This skill is air-gapped from the network by construction.