Best Practices · Workflow · CLI · Cloud Sync · Onboarding

A best-practice pipeline for teams using vem end to end

February 4, 20269 min read

A practical workflow that connects npm install, cloud sync, agents, and Git verification so teams get the full vem ecosystem.

Pipeline map for vem install, sync, and verification — Install, sync, verify: the shortest path to durable memory.

Install and verify the CLI (npm)

The CLI is the authoritative path for writing memory artifacts and pushing snapshots. Install it with npm so it is available across repos and CI machines.

Once installed, run vem --help to confirm the binary is wired.

Install the CLI (npm Packages)

npm install -g @vemdev/cli

Verify

vem --help

Initialize memory and link to the cloud

Initialize the repo so .vem/ becomes the canonical source of truth for tasks, decisions, and changelog entries.

Then authenticate and link the project so snapshots can be indexed and verified against Git commits.

Initialize and link

vem init
vem login <api_key>
vem link <projectId>

Existing repo? Backfill history

If this repo already has commits, run a full reindex so the cloud can build a verified timeline from your Git history.

This is a one-time operation per repo and becomes the foundation for future semantic search and audit trails.

Backfill historical commits

vem reindex --mode full

Create a verified snapshot baseline

Initialize local .vem/ artifacts (gitignored), then push a snapshot to the cloud.

This establishes the pending-to-verified workflow and ensures the dashboard reflects linked Git state.

Commit code and push snapshot

git add .
git commit -m "init project"
vem push
git push

Enable automatic cloud sync

vem can install a git pre-push hook that runs vem push automatically. Accept it during vem init or reinstall it later.

Use vem push after major updates when you want an immediate snapshot in the cloud.

Accept the hook during vem init
If skipped, re-run vem init to install it
Snapshots are marked pending until the Git push verifies them

Use the agent wrapper with strict memory

Run agents through the CLI to get task context injected automatically. Strict memory enforcement is on by default, so each run must produce a vem_update covering context, current_state, changelog, and decisions.

You can disable strict memory if needed using --no-strict-memory or VEM_STRICT_MEMORY=0, but teams should keep it on for best results.

Run an agent

vem agent codex
# or
vem agent --task TASK-201

Disable strict memory (optional)

vem agent --no-strict-memory
# or
VEM_STRICT_MEMORY=0 vem agent codex

Use tasks and task context

Use tasks as the canonical unit of work. Each task gets a stable ID and becomes the record for evidence, validation, and agent signatures.

Append task context during execution, then complete the task with evidence and a concise context summary.

Task intake + context

vem task add "Ship audit log filters" --priority high --description "Improve filter UX" --validation "npm test"
vem task context TASK-201 --append "Filter UX spec finalized"

Complete with evidence

vem task done TASK-201 --evidence "npm test" --reasoning "Added filter state persistence" --actor "Codex" --context-summary "Filters now persist across sessions"

Keep memory verified and searchable

After any memory update, push a snapshot so the cloud can index it immediately.

Verified memory is what powers trusted search, onboarding, and audits across the dashboard and MCP tools.

Push after updates

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

Web dashboard flow: link project + review activity

Use the web dashboard to link the GitHub repo and confirm the installation, then verify the activity timeline reflects your latest pushes.

This gives teams a shared, visual audit trail of memory changes, task updates, and verification events.

Project Settings: link repo + GitHub App installation
Activity: verify recent snapshots and Git verifications

Sync after linking

vem push

Web dashboard showing project linking and activity timeline — Link the repo in settings, then confirm activity in the timeline.

Keep memory clean

As memory grows, archive older decisions, changelogs, and completed tasks so active context stays small and fast for agents.

Archiving moves files into .vem subfolders without deleting history.

Archive older records

vem archive --decisions --older-than 60
vem archive --changelog --keep 10
vem archive --tasks --older-than 30