FAQ

FAQ

What's the difference between this and the on-prem variant?

	Cloud (this repo)	On-prem
Network calls to Box during skills	Yes (via Box MCP)	Zero
Box AI features (Ask, Extract, AI Studio, Hubs Q&A)	Yes (Business+)	Not available
Requires Box Drive installed	No	Yes
Works from any device with internet	Yes	macOS only (Windows in v0.0.4)
Best for	General-purpose memory + file storage	HIPAA / FedRAMP / ITAR data paths

See the air-gapped variant: https://github.com/mrdulasolutions/BOX-Onprem

You can install both — they have separate plugin namespaces (box-memory: vs box-memory-onprem:) and don't conflict.

Do I need Business+ to use the plugin?

No. Personal / Free tier works fine for most agent-memory use cases. You get:

• Memory write/recall via _index.json (sub-second)
• File companions (local-inspection only)
• Multi-team folder structure
• All non-AI skills

Business+ adds:

• Metadata templates → faster structured queries
• Box AI Ask + Extract + (Enterprise Plus) Hubs Q&A
• Body full-text search (10 KB cap per doc)

Does this work with the on-prem variant in the same workspace?

Yes. Same workspace schema. A workspace created with the cloud plugin can be opened by the on-prem plugin and vice versa.

Caveat: if both plugins are writing to the same workspace concurrently, you may see .conflict files for _index.json. The on-prem variant's box-index-rebuild handles those via union-merge.

What's the Box MCP and why does it matter?

The Box MCP (Model Context Protocol) server is what your agent uses to talk to Box. The plugin invokes Box MCP tools (upload_file, list_folder_content, search_files_keyword, box_ai_ask, etc.) under the hood — it doesn't reimplement Box's API.

Use Box's official remote MCP at mcp.box.com. Older self-hosted Box MCPs work for basics but don't expose Box AI tools. See Box MCP Setup and box-mcp-check.

Why are AI features off by default?

To control AI Unit costs. Box charges AI Units per /ai/ask, /ai/extract_structured, and /ai_agents call. Default-off forces explicit opt-in.

To enable, set in _box-memory.json.settings:

ai_recall_enabled: true        # /box-ai-recall
ai_extract_enabled: true       # /box-companion AI path + /box-ai-extract
ai_studio_agent_enabled: true  # /box-ai-agent

See Box AI Units for the cost model.

How do I know if my Box account supports Box AI?

Run /box-tier-detect. It probes:

• Custom metadata templates (Business+)
• Box AI tools availability (requires official remote MCP at mcp.box.com)
• AI Units availability (best-effort check)
• Box Hubs (Enterprise Plus)
• AI Studio (Enterprise Advanced)

Output goes into _box-memory.json.capabilities. Other skills read this to route correctly.

Why does box-recall not find memories I just wrote?

If the memory was written less than ~10 minutes ago AND you're querying via Box Search (not _index.json), Box's search index lag is the cause. See Operational Notes Note 3.

The plugin's default recall path is _index.json which has zero lag — every memory write updates the index in the same operation. If box-recall is genuinely missing a recently-written memory, run /box-index-rebuild --check to inspect for drift.

Why does my Box AI call return 403?

Most likely: OAuth scope ai.readwrite not granted. Run /box-mcp-check to inspect scopes; if ai.readwrite is missing, disconnect and reconnect Box MCP in your platform's settings, granting the scope during OAuth.

Second possibility: stale OAuth token after a tier upgrade. See Operational Notes Note 2.

Why does my Box AI call return 402?

You've exhausted your account's AI Unit allocation for this billing period. See Box AI Units for per-plan allocations and what falls back.

The plugin auto-switches ai_recall_enabled and friends to false for the session after a 402 — explicit user action (box-tier-detect --refresh or workspace config edit) to re-enable.

Can I use the plugin from LangChain or LlamaIndex?

Yes — see Framework Integrations. Box maintains langchain-box and llama-index-readers-box. Use them for the retrieval / loader path; use this plugin's skills for memory writes.

What if I'm using a community Box MCP (like hmk/box-mcp-server)?

The non-AI skills work fine. Box AI skills (box-ai-recall, box-ai-extract, box-ai-agent) require Box's official remote MCP at mcp.box.com which exposes the box_ai_* tools.

Run /box-mcp-check to see what's available. The skill walks you through switching to the official MCP.

Where's the workspace data stored?

In Box, at the path you chose when running /box-init. The plugin writes:

• _box-memory.json at the workspace root (config)
• _index.json per folder (lookup cache)
• memories/<kind>__<slug>.md (the memories themselves)
• files/<name> (binaries you upload)
• companions/<name>.md or sibling (the markdown describing binaries)
• teams/<team-name>/... for multi-team workspaces

You can browse it all in Box's web UI. Nothing about the plugin makes it agent-only.

Can multiple agents write to the same workspace simultaneously?

Yes, with caveats. The plugin uses a workspace lockfile (_box-memory.lock) for the _index.json write path. Two clients writing the same index produce a Box-side .conflict file; box-index-rebuild merges by union + most-recent-wins.

Heavy concurrent use is best-effort eventually-consistent, not transactional. For hard concurrency requirements, serialize at your workflow layer.

How do I uninstall?

Claude Code: rm -rf ~/.claude/plugins/box-memory

Cowork: Settings → Plugins → Box memory → Remove.

Workspace data in Box is not deleted. You'd manually delete the workspace folder via Box's web UI if desired.

See also

• Troubleshooting — error-symptom diagnostic flows
• Operational Notes — eight Box-side quirks
• Box AI Units — cost model