dz setup

dz setup initializes your project for DZ Harness Hub. It creates the configuration files, sets up the skills directory, and optionally configures a persistent memory backend.

Basic Usage

# Standard setup for a target
dz setup --target claude-code

# Setup with agentdb memory backend
dz setup --target claude-code --memory agentdb

--target is required. The optional --preset installs a preset during setup.

What Setup Does

1. Creates the .dz/ directory for harness config and learning data
2. Writes .dz/config.json with default learning settings
3. Configures session/pattern hooks for the target agent platform
4. Sets up the memory backend (JSONL or agentdb)
5. Adds the learning data files to .gitignore

Memory Backends

JSONL (Default)

The default memory backend stores learning patterns as append-only JSONL files in .dz/.

Property	Value
Format	JSON Lines (one record per line)
Storage	.dz/sessions.jsonl + .dz/patterns.jsonl
Persistence	File-based (git-ignored by default)
Query speed	Linear scan (O(n))
Best for	Small projects, simple patterns

agentdb

The agentdb backend provides structured, queryable persistent memory with vector search capabilities.

Property	Value
Format	native SQLite + HNSW store (.dz/agentdb.db)
Storage	.dz/agentdb.db
Persistence	File-based, optionally git-ignored
Query speed	Indexed, vector similarity search
Best for	Large projects, complex pattern matching, team sharing

# Enable agentdb during setup
dz setup --target claude-code --memory agentdb

To switch backends later, re-run dz setup --target <name> --memory agentdb --force.

Comparison

Feature	JSONL	agentdb
Zero dependencies	Yes	Requires the agentdb CLI (npx agentdb)
Human-readable files	Yes	No (binary .dz/agentdb.db store)
Full-text search	No	Yes
Vector similarity	No	Yes
Pattern deduplication	Manual	Automatic
Capacity	Suited to small local stores	Suited to larger searchable stores; measure with your workload
Git-friendly	Yes	Partial (.gitignore recommended)

The --memory agentdb Flag

--memory agentdb activates the AgentDB memory backend during setup. AgentDB is a persistent, queryable memory layer backed by a native SQLite + HNSW store (.dz/agentdb.db). It powers the self-learning loop for dz recommend, dz teach, and dz pretrain.

Setup installs agentdb + better-sqlite3 locally (pinned exact), writes .dz/agentdb-writer.mjs, and registers the MCP server in .mcp.json (the project-scope file Claude Code loads) with AGENTDB_PATH pinned to .dz/agentdb.db. The session hooks make real writes into that shared store — instant metadata rows in the dz_session_events table (telemetry, deliberately outside the vector index; no model load, ~ms). Real learnings enter the vector index in-session via the agentdb_* MCP tools. The writer degrades to a .dz/sessions.jsonl marker only if better-sqlite3 is unavailable, and carries a version stamp — re-running dz setup upgrades it without --force. dz doctor flags legacy installs (broken agentdb add hooks, orphan .dz/memory.rvf, stale .claude/mcp.json).

# Standard setup (JSONL — simple, git-friendly)
dz setup --target claude-code

# Setup with agentdb (scalable, semantic search)
dz setup --target claude-code --memory agentdb

The AgentDB integration exposes MCP tools and a hierarchical memory model (working / short-term / long-term tiers) backed by an HNSW vector index in a single .dz/agentdb.db file. The exact tool set depends on the installed version:

Tier	Description
working	Active patterns for the current session
short-term	Recent patterns retained across nearby sessions
long-term	Consolidated patterns with semantic (HNSW) similarity search

See the learning guide for the memory workflow and the published MCP package for the current integration files.

JSONL vs AgentDB — When to Use Which

Scenario	Recommended Backend
Small project, single developer	JSONL (default)
Large codebase (10K+ files)	agentdb
Team sharing patterns across machines	agentdb
Need semantic / similarity search	agentdb
Git-tracked memory in repo	JSONL
CI/CD integration with pattern queries	agentdb

Options

Flag	Description
--target <platform>	Target agent (required): claude-code, codex, opencode, hermes, openclaude
--preset <name>	Install a preset during setup
--memory agentdb	Use the agentdb vector memory backend (default is JSONL)
--no-hooks	Skip writing session/pattern hooks
--install-driver	Install the platform driver/runtime if applicable
--force	Overwrite existing configuration

Examples

# Full setup with agentdb and the devops preset
dz setup --target claude-code --memory agentdb --preset devops

# Setup for Codex target
dz setup --target codex

# Re-initialize (overwrite existing config)
dz setup --target claude-code --force

Post-Setup

After running dz setup, you typically want to:

# Install a preset for your target
dz init --target claude-code --preset devops

# Verify installation
dz doctor

# Pre-train on your codebase
dz pretrain

# Get recommendations for a task
dz recommend "add integration tests for the payment service"