tx learning
Record and search knowledge for future agents
Purpose
Learnings are pieces of knowledge that persist across sessions and can be retrieved based on context. They're the memory layer that helps agents avoid repeating mistakes and build on past insights.
Commands
| Command | Description |
|---|---|
tx learning:add | Add a new learning |
tx learning:search | Search learnings by query |
tx learning:recent | List recently added learnings |
tx learning:helpful | Record whether a learning was helpful |
tx learning:embed | Compute embeddings for vector search |
tx learning:add
Add a new learning to the knowledge base.
Usage
tx learning:add <content> [options]Arguments
| Argument | Required | Description |
|---|---|---|
<content> | Yes | The learning content/insight to store |
Options
| Option | Description |
|---|---|
-c, --category <cat> | Category tag (e.g., database, auth, api) |
--source-ref <ref> | Reference to source (e.g., task ID, file path) |
--source-type <type> | Source type: manual, compaction, run, claude_md (default: manual) |
--json | Output as JSON |
Examples
# Basic learning
tx learning:add "Always use transactions for multi-step DB operations"
# With category
tx learning:add "Rate limit is 100 req/min" -c api
# With source reference
tx learning:add "Migration requires downtime" --source-ref tx-abc123tx learning:search
Search learnings using BM25 full-text search with recency weighting.
Usage
tx learning:search <query> [options]Arguments
| Argument | Required | Description |
|---|---|---|
<query> | Yes | Search query (keywords or phrase) |
Options
| Option | Description |
|---|---|
-n, --limit <n> | Maximum results (default: 10) |
--min-score <n> | Minimum relevance score 0-1 (default: 0.3) |
--json | Output as JSON |
Examples
# Basic search
tx learning:search "database transactions"
# Limited results with JSON output
tx learning:search "authentication" -n 5 --jsonOutput
Search results for "database transactions":
1. [0.89] Always use transactions for multi-step DB operations
Category: database | Source: manual
2. [0.72] Enable WAL mode for better concurrent read performance
Category: database | Source: tx-def456
3. [0.65] Use connection pooling with max 10 connections
Category: database | Source: compactiontx learning:recent
List recently added learnings.
Usage
tx learning:recent [options]Options
| Option | Description |
|---|---|
-n, --limit <n> | Maximum results (default: 10) |
--json | Output as JSON |
Examples
# Recent learnings
tx learning:recent
# Last 5 learnings as JSON
tx learning:recent -n 5 --jsontx learning:helpful
Record whether a learning was helpful for a task. This feedback improves future retrieval.
Usage
tx learning:helpful <learning-id> <task-id> --yes|--noExamples
# Mark a learning as helpful
tx learning:helpful lr-abc123 tx-def456 --yes
# Mark a learning as not helpful
tx learning:helpful lr-abc123 tx-def456 --noEmbeddings
Embeddings are computed automatically when a learning is created via tx learning:add. If an embedder is configured (OpenAI or local model), the embedding is stored immediately so vector search works without any extra steps.
If no embedder is available, the learning is still created (with embedding = NULL) and search falls back to BM25-only.
tx learning:embed
Batch-compute embeddings for learnings that don't have them yet. Useful for backfilling older learnings or re-embedding with a different model.
Usage
tx learning:embed [options]Options
| Option | Description |
|---|---|
--all | Recompute all embeddings (including already-embedded) |
--embedder <type> | Select embedder: auto, openai, local, noop |
--status | Show embedding coverage status |
--json | Output as JSON |
Examples
# Backfill embeddings for learnings without them
TX_EMBEDDINGS=1 tx learning:embed
# Recompute all embeddings
TX_EMBEDDINGS=1 tx learning:embed --all
# Check coverage
tx learning:embed --statusThe Knowledge Layer
Learnings form the knowledge layer in tx's architecture:
┌─────────────────────────────────────────┐
│ Agent Orchestration │
├─────────────────────────────────────────┤
│ Task Management (ready, block, done) │
├─────────────────────────────────────────┤
│ Memory / Knowledge Graph │ ← Learnings live here
├─────────────────────────────────────────┤
│ Storage (Git + SQLite) │
└─────────────────────────────────────────┘Learnings compound over time. As agents complete tasks and record insights, future agents get smarter.
Agent Workflow
#!/bin/bash
# Record a learning after completing a task
# Complete the task
tx done tx-abc123
# Record what was learned
tx learning:add "React Query handles cache invalidation automatically" \
-c frontend \
--source-ref tx-abc123Related Commands
tx context- Get learnings relevant to a tasktx learn- Attach a learning to a file/glob patterntx recall- Query learnings for a specific path