MuninnDB

Vault Management

Overview

A vault is a named, isolated namespace for engrams. Each vault has its own memories, indexes, and access keys — no data crosses vault boundaries.

Vault management lets you clone a vault into a new one, wipe all memories from a vault, or permanently remove a vault entirely. These are admin operations. All CLI commands require an admin session; all REST endpoints require an mn_admin_ token.

Clear vs. Delete

These two operations sound similar but do different things. Read this before proceeding.

Operation Removes memories? Removes vault name? Reversible?
vault clear Yes — all memories deleted No — vault name stays No
vault delete Yes — all memories deleted Yes — vault name freed No

Use clear to wipe a vault's contents and reuse the name. Use delete to remove the vault entirely.

Vault Name Rules

Vault names must be 1–64 characters: lowercase letters, digits, hyphens, and underscores only. No spaces, no uppercase.

Name Valid?
prod-memories ✓ Yes
staging_test ✓ Yes
agent42 ✓ Yes
My Vault ✗ No — spaces not allowed
ProdVault ✗ No — uppercase not allowed
(empty) ✗ No — at least 1 character required

Listing Vaults

See all vaults on the node:

bash 
muninn vault list

# NAME               ENGRAMS   CREATED
# default             12,450   2026-01-05
# prod-memories        8,200   2026-01-12
# staging-test            42   2026-02-18

Cloning a Vault

Clone copies all memories, associations, metadata, and embeddings from an existing vault into a brand-new vault. The operation runs as a background job so your workload isn't blocked. It completes in two phases: first it copies raw data, then it rebuilds indexes so the new vault is fully queryable.

# Clone a vault into a new one
muninn vault clone prod-memories staging-test

# Cloning prod-memories → staging-test
# [████████░░] copying  4,200 / 5,000 engrams  (84%)
# [██░░░░░░░░] indexing   800 / 5,000 engrams  (16%)
# ✓ Clone complete in 42s

Monitoring Clone Progress

The CLI polls job status every 500ms and shows a live progress bar. If the clone takes longer than 30 minutes, the CLI prints the job ID and exits — the job keeps running in the background. Use the commands below to check it:

# The CLI polls automatically. To check a job manually:
muninn vault job-status staging-test --job-id job-abc123xyz

Job states in order:

  • copying — raw data is being transferred to the new vault
  • indexing — FTS and vector indexes are being rebuilt
  • done — clone is complete, the vault is ready to use
  • error — clone failed; read the error field for the reason

If a clone fails mid-way: A partial vault is left behind. Delete it with muninn vault delete <target-name> --yes before retrying the clone.

Situation HTTP What to do
Source vault not found 404 Verify source name with vault list
Target name already exists 409 Choose a different name, or delete the existing vault first
Cloning a vault onto itself 409 Target name must differ from source
Invalid vault name 400 Follow vault name rules above

Clearing a Vault

Irreversible. All memories in the vault will be permanently removed. The vault name is kept. There is no undo.

Clearing removes all engrams, associations, cached indexes, and embeddings. The vault registration stays intact — existing API keys remain valid and agents can immediately write new memories to the now-empty vault.

# Interactive — prompts you to type the vault name:
muninn vault clear test-vault

# Vault: test-vault
# This will permanently delete all memories in this vault.
# Type the vault name to confirm: test-vault
# ✓ Vault cleared.

# Scripted / CI — skip the prompt:
muninn vault clear test-vault --yes
Situation HTTP What to do
Vault not found 404 Verify name with vault list
Clearing default vault without --force 409 Add --force flag (see Default Vault below)
Invalid vault name 400 Follow vault name rules above

Deleting a Vault

Permanent. The vault and every memory in it will be deleted. The vault name is freed. This cannot be undone.

Delete is a two-step operation: it first clears all memories, then removes the vault registration. Once deleted, the vault name can be reused for a new vault.

You cannot delete a vault while a clone job is targeting it. If a clone is actively reading or writing this vault, the delete is rejected with a 409. Wait for the job to finish, then retry.

# Interactive — prompts you to type the vault name:
muninn vault delete old-vault

# Vault: old-vault
# This will permanently delete the vault and ALL its memories.
# This cannot be undone. Type the vault name to confirm: old-vault
# ✓ Vault deleted.

# Scripted / CI — skip the prompt:
muninn vault delete old-vault --yes
Situation HTTP What to do
Vault not found 404 Verify name with vault list
Active clone/merge job in progress 409 Wait for the job to finish, then retry
Deleting default vault without --force 409 Add --force flag (see Default Vault below)
Invalid vault name 400 Follow vault name rules above

Protecting the Default Vault

MuninnDB ships with a vault named default. Every agent that doesn't specify an explicit vault parameter writes and reads from this one. Because wiping it affects every agent on the node, MuninnDB refuses to clear or delete default unless you explicitly opt in. The CLI uses a --force flag; the REST API uses an X-Allow-Default: true header — same intent, different surface.

bash — forced clear / delete of the default vault 
# CLI
muninn vault clear  default --force --yes
muninn vault delete default --force --yes

# REST — pass the override header
curl -X POST   http://localhost:8475/api/admin/vaults/default/clear  -H "X-Allow-Default: true" -H "Authorization: Bearer mn_admin_..."
curl -X DELETE http://localhost:8475/api/admin/vaults/default         -H "X-Allow-Default: true" -H "Authorization: Bearer mn_admin_..."

What happens to agents after you clear the default vault? Their API keys stay valid. Every ACTIVATE query returns zero results until new memories are written. Agents won't notice an error — the vault just appears empty.

What happens after you delete the default vault? The name default is freed. MuninnDB does not recreate it automatically. Agents will receive a 404 on every request until you create a new vault named default.

Tip: Before clearing or deleting the default vault in production, clone it first as a safety net — muninn vault clone default default-backup-$(date +%F). Clones take seconds for small vaults.

← Previous Next →