Self-Learning Guide

DZ Harness Hub includes a self-learning system that improves skill recommendations and behavior over time. The loop has stages: setup, teach, consolidate, recall, and recommend — all backed by a unified @dzhechkov/memory store.

The Learning Loop

dz setup --memory agentdb
       |
       v
  dz teach <pattern>  ──┐     dz consolidate  (harvest session
       |                │      transcripts → store; auto-discovers
       v                │      your Claude Code transcript dir)
  unified memory store ◄┘            │
       │   ▲                          │
       │   └──────────────────────────┘
       ├──► dz recommend  ──► reward-ranked skill suggestions (boost from learned patterns)
       └──► dz recall "<q>" ──► ranked lexical search (SQLite FTS5) over what you've learned

• dz teach "<pattern>" --reward <0-1> --domain <name> — record a pattern; it’s read back into dz recommend.
• dz consolidate — harvest tool-use + checkpoint outcomes from session transcripts into the store. Idempotent + incremental (durable watermark); auto-discovers .dz/sessions then your host Claude Code transcript dir, so usually no --sessions-dir needed. On the agentdb backend it also mirrors each NEW learning into the vector index (ReasoningBank, real embeddings, the harvested score as successRate) — so agentdb_pattern_search recalls your session learnings semantically; --no-mirror disables. The SessionEnd hook fires this automatically (detached, off the critical path).
• dz recall "<query>" — ranked search over the learned store (SQLite FTS5 when available, keyword otherwise). True semantic (vector) recall lives in the agentdb-memory MCP skill.
• dz stats — shows the current project’s learn-loop state (learned-pattern count + last consolidation).

Stage 1: Setup

Initialize the memory backend. See the dz setup guide for details.

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

# agentdb backend (queryable, scalable)
dz setup --target claude-code --memory agentdb

Stage 2: Teach

Feed patterns into the harness. Patterns are observations about your project, team conventions, or workflow preferences.

# Teach a simple pattern
dz teach "always run tests before committing"

# Teach with a reward weight (0-1) and a domain
dz teach "prefer vitest over jest" --reward 0.9 --domain testing

# Tag the pattern type explicitly
dz teach "never use the any type" --type rule

dz teach takes the pattern as a positional argument and supports --reward <0-1>, --domain <name>, and --type <name>. To learn many patterns at once from your codebase, use dz pretrain (below).

Pattern Types

dz teach classifies each pattern as one of three types (auto-detected from the text, or set with --type):

Type	When	Example
rule	imperative phrasing (always / never / use / avoid / prefer / when / before / after)	“always run tests before committing”
success-pattern	a positive outcome with reward ≥ 0.8	“DataLoader fixed the N+1 query” (--reward 0.9)
lesson-learned	anything else (lower-reward observations)	“the legacy auth module is brittle”

Record Format

Patterns are stored as canonical MemoryRecords in the unified @dzhechkov/memory store (.dz/memory/patterns.sqlite when better-sqlite3 is available, else .dz/memory/patterns.json). Each taught pattern maps from this shape:

{"pattern":"always run tests before committing","type":"rule","reward":0.8,"domain":"workflow","ts":"2026-06-24T00:00:00.000Z","source":"dz-teach"}
{"pattern":"prefer vitest over jest","type":"success-pattern","reward":0.9,"domain":"testing","ts":"2026-06-24T00:00:00.000Z","source":"dz-teach"}

reward (0–1) drives a monotonic, capped boost in dz recommend; domain and pattern text drive matching. Retention (learning.retentionDays, default 90) drops stale records at read time.

Semantic (vector) recall

The CLI ranks lexically (SQLite FTS5 / keyword). True semantic / HNSW vector recall — embeddings, similarity, decay — lives in the agentdb-memory MCP skill (.dz/agentdb.db), which runs inside your agent session, not from dz recall.

Stage 3: Recommend

The dz recommend command analyzes your project and suggests skills based on:

1. Tech stack detection — languages, frameworks, package.json, config files
2. Learned patterns — conventions and preferences from dz teach
3. Usage history — which skills you use most (and least)
4. Project structure — monorepo vs single-package, test coverage, CI setup

# Get recommendations for a task
dz recommend "set up CI/CD with security scanning"

# Describe the area you want help with
dz recommend "audit the auth module for vulnerabilities"

dz recommend takes a single task description as a positional argument; it has no flags.

Pre-Training

dz pretrain scans your codebase and extracts patterns automatically — no manual teaching needed.

# Pre-train on the current project
dz pretrain

# Pre-train on a specific project directory
dz pretrain --project ./packages/api

dz pretrain accepts only --project <dir> (defaults to the current directory).

Pre-training extracts:

• File naming conventions
• Test framework preferences
• Import patterns
• Configuration styles
• CI/CD patterns from workflow files

Integration with AgentDB

The AgentDB memory backend adds a hierarchical memory model and semantic search. Check the published MCP package for the integration supported by your installed release.

Hierarchical Memory

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

Patterns are stored in a single .dz/agentdb.db HNSW vector file. Frequently used patterns are promoted to longer-term tiers; stale patterns decay in confidence.

MCP Tools

The agentdb-memory skill exposes tools covering:

• Pattern CRUD (store, get, update, delete, list)
• Semantic search (embedding-based similarity)
• Cross-session merge and deduplication
• Confidence decay and staleness tracking
• Export / import for team sharing

Install the skill to activate these tools in Claude Code:

dz install @dzhechkov/skills-mcp
# then enable the agentdb-memory skill

Additional Capabilities

• Semantic search — find similar patterns even with different wording
• Decay and freshness — old patterns automatically lose weight
• Conflict resolution — contradictory patterns are flagged for review

Taught/consolidated patterns live in the unified store under .dz/memory/ (patterns.sqlite or patterns.json); a legacy .dz/patterns.jsonl is still read and folded in if present. To share patterns across machines, commit (or copy) the .dz/memory/ directory. The agentdb .dz/agentdb.db (vector store) is managed by the agentdb-memory MCP skill.

Benchmarking the Learning Effect

Use dz benchmark to measure how learning improves skill performance:

# Benchmark a skill directory
dz benchmark .claude/skills/pr-review

# Teach some patterns
dz teach "our PRs must include test coverage" --domain review

# A/B compare two skill versions
dz benchmark .claude/skills/pr-review --compare ./pr-review-v2