Docs/Guides

Guides

Deep dives into how vem works, how to structure memory, and how to coordinate human + agent workflows.

Core concepts

Cloud snapshots are canonical

Local .vem/ is your workspace state; the cloud snapshot timeline is the shared source of truth.

Memory is explicit

Tasks, context, decisions, and changelogs are structured files under .vem/.

Snapshots are the contract

Push and pull snapshots to synchronize state across machines and agents.

Security is enforced

Seats, API keys, and MFA protect your project's memory integrity.

Verification & Integrity

vem ensures your project memory is trustworthy through automated checks and verification signals.

Truth Drift Detection

Tasks marked 'done' without evidence are flagged as 'suspicious' to prevent hallucinations.

Secret Detection

Snapshot payloads are automatically scanned and rejected if they contain private keys or tokens.

Task Validation

Define mandatory steps (e.g., 'pnpm test') that must be confirmed before a task can be closed.

Offline Queue

If a push fails due to network issues, vem enqueues it locally and retries on the next sync.

Validation steps are task-level requirements like pnpm build or pnpm test. Agents must confirm them before closing a task, and the evidence history records the verification.

Example: vem task add "API cleanup" --validation "pnpm build"

Memory structure

vem keeps workspace memory inside .vem/. The folder is local and gitignored by default.

.vem/
  CONTEXT.md        # Project summary
  CURRENT_STATE.md  # Latest progress + next steps
  current_context.md # Generated pack snapshot (do not edit)
  changelog/        # Dated changelog entries
  decisions/        # ADR entries
  tasks/index.json  # Task index
  tasks/objects/    # Task objects
  tasks/archive/    # Archived tasks
  config.json       # Local vem metadata
  queue/            # Offline snapshot queue

Snapshot workflow

Push updates

After editing local memory, push a snapshot so the cloud index stays current.

git add .
git commit -m "ship change"
vem push

Pull on new machines

When you switch devices, pull the latest snapshot before continuing.

vem pull

Resolve snapshot conflicts

If base versions diverge, pull the latest snapshot, reconcile local memory, then push again.

vem pull
# reconcile local .vem state
vem push

Human + agent workflows

Teams and seats

Seat assignments gate write access to projects, keys, and snapshots.

MCP integrations

Agents can read tasks, search memory, and record decisions via MCP tools.

Always run vem push after memory changes. Agents are transient; snapshots keep decisions verifiable across machines.

Need help wiring MCP? Start with npx vem-mcp and add it to your agent client config.

Security & enforcement

API key enforcement

Keys identify the org and user to enforce seats on every write.

Multi-Factor Authentication

Enforce MFA (TOTP) across your organization to protect sensitive memory.

If a user has no seat or fails MFA enforcement, write operations are restricted.

Next steps

Quickstart

Install the CLI and push your first snapshot.

API reference

Inspect the REST endpoints and payloads.