Schema

Schema

The workspace, memory, companion, and index file formats. Same schema as the cloud variant — both plugins read and write the same shapes. This repo pins to a specific commit of the cloud repo via .schema-pin.

Source of truth: synced/schema.md (fetched from cloud repo at .schema-pin). Or read the cloud wiki: BOX Schema page.

File types

1. _box-memory.json — workspace config (one per workspace, at the root)
2. Memory files — markdown with YAML frontmatter, one per memory
3. Companion files — markdown describing a binary, kind: companion memory
4. _index.json — per-folder index for instant lookup

On-prem-specific schema notes

The same schema works for both variants with small differences in field population:

Field	Cloud variant	On-prem variant
entries[].file_id	Box file ID (immediate)	null — Box assigns IDs only after sync
entries[].local_path	Optional	Canonical — relative path from workspace root
_box-memory.json.backend	cloud (or unset)	local
_box-memory.json.workspace_owner_app	box-memory	box-memory-onprem
_box-memory.json.local_backend	Absent	Populated by box-drive-detect
workspace_type	folder or hub	folder only (Hubs require Box AI)
metadata_template_key	boxMemory (on Business+)	null (no Box API to apply templates)

A workspace created by either variant can be opened by the other. The cloud variant fills in file_id on first read after sync; the on-prem variant uses local_path for everything.

Lockfile protocol

When writing _box-memory.json or any _index.json:

1. Create <workspace>/_box-memory.lock with O_CREAT|O_EXCL. Body:

{ "writer": "box-memory-onprem", "skill": "box-write", "pid": <pid>, "started_at": "<ISO>", "renewed_at": "<ISO>" }

2. If exists, check renewed_at. If <30 s old, retry up to 3× with 5 s backoff. If ≥30 s old, force-release.
3. While holding, update renewed_at every 10 s if the operation runs longer.
4. Write target atomically: <file>.tmp → fsync → rename.
5. Release lock: delete the lockfile.

The lockfile is in the Box Drive mount — Box Drive syncs it. Two machines writing concurrently see the lock (eventually). This is best-effort eventually-consistent, not transactional.

.conflict file handling

Box Drive creates <filename>.conflict-<timestamp> when two clients write the same file concurrently. The plugin's box-index-rebuild merges _index.json.conflict-* files by:

• Union of entries
• Most-recent updated_at wins per entry ID

For memory .md files, no auto-merge — surface in box-index-rebuild --check for user decision.

Compliance declaration fields

_box-memory.json.settings supports optional compliance declaration:

settings:
  compliance_target: hipaa | fedramp-moderate | fedramp-high | il4 | itar | gxp | gdpr | null
  box_plan: business | enterprise | enterprise-plus | enterprise-advanced | box-federal
  box_addons: [governance, keysafe, zones, shield]
  box_zone: us-east | us-west | gov | eu-ireland | eu-germany | uk | au-sydney | jp-tokyo | sg-singapore
  baa_signed: <date or null>

/box-airgap-status reads these and flags mismatches with the LLM provider's compliance posture.

See also

• Compliance by Deployment — uses these declaration fields
• box-init — writes the workspace config
• Source: synced/schema.md
• Cloud wiki Schema: https://github.com/mrdulasolutions/BOX/wiki/Schema