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.

tx learning:add <content> [options]

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-abc123

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

const learning = await tx.learnings.add({
  content: 'Always use transactions for multi-step DB operations',
  sourceType: 'manual',
  sourceRef: 'tx-abc123',
  category: 'database',
  keywords: ['transaction', 'database']
})

Tool name: tx_learning_add

Arguments:

Arg	Type	Required	Description
`content`	`string`	Yes	The learning content/insight to store
`category`	`string`	No	Category tag
`sourceRef`	`string`	No	Reference to source
`sourceType`	`string`	No	Source type (default: manual)

Example request:

{
  "name": "tx_learning_add",
  "arguments": {
    "content": "Always use transactions for multi-step DB operations",
    "category": "database",
    "sourceRef": "tx-abc123"
  }
}

POST /api/learnings

Body:

{
  "content": "Always use transactions for multi-step DB operations",
  "category": "database",
  "sourceRef": "tx-abc123",
  "sourceType": "manual"
}

Example:

curl -X POST http://localhost:3456/api/learnings \
  -H "Content-Type: application/json" \
  -d '{"content": "Always use transactions for multi-step DB operations", "category": "database"}'

tx learning:search

Search learnings using BM25 full-text search with recency weighting.

tx learning:search <query> [options]

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 --json

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

const results = await tx.learnings.search({
  query: 'database transactions',
  limit: 10,
  minScore: 0.3,
  category: 'database'
})

for (const r of results) {
  console.log(`[${r.relevanceScore.toFixed(2)}] ${r.content}`)
}

Tool name: tx_learning_search

Arguments:

Arg	Type	Required	Description
`query`	`string`	Yes	Search query
`limit`	`number`	No	Maximum results (default: 10)
`minScore`	`number`	No	Minimum relevance score 0-1 (default: 0.3)
`category`	`string`	No	Filter by category

Example request:

{
  "name": "tx_learning_search",
  "arguments": {
    "query": "database transactions",
    "limit": 5
  }
}

GET /api/learnings?query=database+transactions&limit=10

Query parameters:

Param	Type	Required	Description
`query`	`string`	Yes	Search query
`limit`	`number`	No	Maximum results (default: 10)
`minScore`	`number`	No	Minimum relevance score 0-1
`category`	`string`	No	Filter by category

Example:

curl "http://localhost:3456/api/learnings?query=database+transactions&limit=5"

Output

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: compaction

tx learning:recent

List recently added learnings.

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 --json

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

// Search with empty query and sort by recency
const recent = await tx.learnings.search({
  query: '',
  limit: 10
})

Tool name: tx_learning_search

Use the search tool with an empty query to get recent learnings:

{
  "name": "tx_learning_search",
  "arguments": {
    "query": "",
    "limit": 10
  }
}

GET /api/learnings?limit=10

Omit the query parameter to get recent learnings sorted by creation time.

Example:

curl "http://localhost:3456/api/learnings?limit=10"

tx learning:helpful

Record whether a learning was helpful for a task. This feedback improves future retrieval.

tx learning:helpful <learning-id> <task-id> --yes|--no

Examples:

# Mark a learning as helpful
tx learning:helpful 42 tx-def456 --yes

# Mark a learning as not helpful
tx learning:helpful 42 tx-def456 --no

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

// Record that learning #42 was helpful
await tx.learnings.helpful(42)

Tool name: tx_learning_helpful

Arguments:

Arg	Type	Required	Description
`id`	`number`	Yes	Learning ID
`taskId`	`string`	Yes	Task ID that used this learning
`helpful`	`boolean`	Yes	Whether the learning was helpful

Example request:

{
  "name": "tx_learning_helpful",
  "arguments": {
    "id": 42,
    "taskId": "tx-def456",
    "helpful": true
  }
}

POST /api/learnings/:id/helpful

Path parameters:

Param	Type	Required	Description
`id`	`number`	Yes	Learning ID

Body:

{
  "taskId": "tx-def456",
  "helpful": true
}

Example:

curl -X POST http://localhost:3456/api/learnings/42/helpful \
  -H "Content-Type: application/json" \
  -d '{"taskId": "tx-def456", "helpful": true}'

tx learning:get

Retrieve a specific learning by its ID.

tx learning:get <id> [--json]

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

const learning = await tx.learnings.get(42)
console.log(learning.content)

Tool name: tx_learning_get

Arguments:

Arg	Type	Required	Description
`id`	`number`	Yes	Learning ID

Example request:

{
  "name": "tx_learning_get",
  "arguments": {
    "id": 42
  }
}

GET /api/learnings/:id

Path parameters:

Param	Type	Required	Description
`id`	`number`	Yes	Learning ID

Example:

curl http://localhost:3456/api/learnings/42

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.

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 [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 --status

File Learnings

Attach learnings to specific file patterns for path-based retrieval.

# Attach a learning to a file pattern
tx learn "src/auth.ts" "JWT tokens expire after 1 hour"

# Recall learnings for a specific file
tx recall "src/auth.ts"

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

// List learnings for a file
const fileLearnings = await tx.fileLearnings.list('src/auth.ts')

// Add a file-specific learning
await tx.fileLearnings.add({
  filePattern: 'src/auth.ts',
  note: 'JWT tokens expire after 1 hour',
  taskId: 'tx-abc123'
})

// Recall learnings matching a path
const notes = await tx.fileLearnings.recall('src/auth.ts')

Tool name: tx_file_learning_list

Arguments:

Arg	Type	Required	Description
`path`	`string`	No	File path to filter by

Tool name: tx_file_learning_add

Arg	Type	Required	Description
`filePattern`	`string`	Yes	Glob pattern or file path
`note`	`string`	Yes	Note to associate with matching files
`taskId`	`string`	No	Task ID that produced this learning

Example request:

{
  "name": "tx_file_learning_add",
  "arguments": {
    "filePattern": "src/auth.ts",
    "note": "JWT tokens expire after 1 hour",
    "taskId": "tx-abc123"
  }
}

List file learnings

GET /api/file-learnings?path=src/auth.ts

Add a file learning

POST /api/file-learnings

Body:

{
  "filePattern": "src/auth.ts",
  "note": "JWT tokens expire after 1 hour",
  "taskId": "tx-abc123"
}

Example:

# List file learnings
curl "http://localhost:3456/api/file-learnings?path=src/auth.ts"

# Add a file learning
curl -X POST http://localhost:3456/api/file-learnings \
  -H "Content-Type: application/json" \
  -d '{"filePattern": "src/auth.ts", "note": "JWT tokens expire after 1 hour"}'

The 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-abc123

tx context - Get learnings relevant to a task
tx learn - Attach a learning to a file/glob pattern
tx recall - Query learnings for a specific path

tx learning

On this page