Schema

Schema

The workspace, memory, companion, and index file formats. Single source of truth for both the cloud and on-prem plugins.

The full schema is at references/schema.md. This wiki page summarizes — refer to the source for the canonical reference.

File types

A box-memory workspace has four 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, special-kind memory
4. _index.json — per-folder index of memory metadata

Memory file

Filename: <kind>__<slug>.md (double underscore separator).

Frontmatter (required fields):

Field	Type	Notes
id	string	ULID prefixed mem_. Never changes.
slug	string	Kebab-case. Stable. Used in filename.
title	string	Plain English. Wikilink target.
kind	enum	decision / fact / task / observation / reference / note / companion
status	enum	active / draft / superseded / archived / held
created_at, updated_at	ISO-8601 UTC	Update updated_at on every write

Optional: team, agent, confidence, tags, related (wikilinks), links, sources, supersedes, superseded_by, expires_at.

Companion file

kind: companion. Filename <original-filename>.md. Adds required frontmatter:

companion_for:
  file_id: "<Box file ID>"
  filename: "<original filename>"
  sha256: "<hash at review time>"
  hash_algo: sha256
  size_bytes: <int>
  mime_type: "<mime>"
  reviewed_at: <ISO>
  reviewed_by: <agent>
  extracted_via: box-ai-extract-structured   # if Box AI extracted
  extracted_at: <ISO>                         # if Box AI extracted

Index file

One per folder. Inverted maps for instant lookup by id, slug, wikilink target, kind, tag, status, companion target.

{
  "version": 1,
  "folder_id": "<Box folder ID>",
  "folder_path": "memories/",
  "updated_at": "<ISO>",
  "tier": "personal | business | enterprise",
  "entry_count": <int>,
  "entries": [...],
  "by_id": {...},
  "by_slug": {...},
  "by_wikilink": {...},
  "by_kind": {...},
  "by_tag": {...},
  "by_status": {...},
  "by_companion_for": {...}
}

Workspace config

_box-memory.json at the root. Captures tier, capabilities, teams, folder IDs, settings.

Key v0.1.0 additions:

workspace_type: folder | hub        # Hub-backed workspaces unlock Hubs Q&A
hub:                                 # only if workspace_type=hub
  id: <Hub ID>
  created_at: <ISO>
  last_item_added_at: <ISO>
settings:
  ai_recall_enabled: false           # opt-in for box-ai-recall
  ai_extract_enabled: false          # opt-in for box-companion AI path
  ai_studio_agent_enabled: false     # opt-in for box-ai-agent
  ai_model: null                     # let Box pick (default GPT-5 mini)
  compliance_target: null            # hipaa | fedramp-* | il4 | itar | gxp | gdpr
ai_studio_agent:                     # populated by /box-ai-agent create
  id: <agent ID>
  name: <agent name>
  created_at: <ISO>
  workspace_scope: folder | hub
  model: <model>

Metadata template (Business+)

Canonical name: boxMemory. Created by box-init on Business+. Targets Box AI Extract Structured.

Fields: memory_id, slug, title, kind, status, team, agent, tags, companion_for_file_id, sha256, created_at, updated_at.

Once present, every memory write also applies a template instance to the file, and recall via mdfilters is fast.

ID generation rules

• Memory ID = ULID (timestamp + random). Sortable, URL-safe. Prefix mem_.
• Slug derived from title: lowercase, non-alphanumeric → hyphens, collapse runs, trim.
• Filename: <kind>__<slug>.md. Slug collisions: append -2, -3, etc.
• Wikilink target = the memory's title field, not the filename or slug.

Conventions agents must follow

1. Never reuse a memory ID
2. Update updated_at on every write
3. Update the folder's _index.json on every write
4. Set status: superseded and superseded_by on the old memory when writing a replacement
5. Filename uses double-underscore separator
6. Wikilink target is the title, not the filename

See also

• Tier Matrix — what capabilities each tier unlocks
• Architecture — why this schema
• Full reference: references/schema.md