tx context

Get contextual learnings for a task

Purpose

tx context retrieves learnings that are relevant to a specific task. It uses the task's title and description to find matching knowledge, making it easy to inject relevant context into agent prompts.

The search uses hybrid BM25 + vector search with RRF fusion, optional re-ranking, and MMR diversification.

Usage

tx context <task-id> [options]

# Get context for a task
tx context tx-abc123

# Write context to .tx/context.md for injection
tx context tx-abc123 --inject

# Get context as JSON for programmatic use
tx context tx-abc123 --json

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

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

// Or direct SQLite mode
const tx = new TxClient({ dbPath: '.tx/tasks.db' })

// Get context for a task
const ctx = await tx.context.forTask('tx-abc123')
// Returns:
// {
//   taskId: string
//   taskTitle: string
//   learnings: SerializedLearningWithScore[]
//   searchQuery: string
//   searchDuration: number
// }

console.log(`Found ${ctx.learnings.length} relevant learnings`)
for (const l of ctx.learnings) {
  console.log(`- [${(l.relevanceScore * 100).toFixed(0)}%] ${l.content}`)
}

Each learning in the response includes relevanceScore, bm25Score, and vectorScore fields.

Tool name: tx_context

Arguments:

Arg	Type	Required	Description
`taskId`	`string`	Yes	Task ID (e.g., `tx-abc123`)

Example request:

{
  "name": "tx_context",
  "arguments": {
    "taskId": "tx-abc123"
  }
}

GET /api/context/:taskId

Path parameters:

Param	Type	Required	Description
`taskId`	`string`	Yes	Task ID (e.g., `tx-abc123`)

Example:

curl http://localhost:3456/api/context/tx-abc123

Options

Option	Description
`--json`	Output as JSON
`--inject`	Write to `.tx/context.md` for injection
`--retriever <path>`	Use custom retriever module
`--help`	Show help

Output

Text Output

Context for task tx-abc123: "Implement authentication"

Relevant learnings:
  1. [0.92] Always hash passwords with bcrypt, never store plaintext
     Category: security | Source: tx-def456

  2. [0.85] Use JWT tokens with short expiry (15min) and refresh tokens
     Category: auth | Source: manual

  3. [0.78] Rate limit login attempts to prevent brute force attacks
     Category: security | Source: tx-ghi789

JSON Output

{
  "task": {
    "id": "tx-abc123",
    "title": "Implement authentication"
  },
  "learnings": [
    {
      "id": "lr-abc123",
      "content": "Always hash passwords with bcrypt, never store plaintext",
      "category": "security",
      "score": 0.92,
      "sourceRef": "tx-def456"
    }
  ]
}

Injection Mode

The --inject flag writes learnings to .tx/context.md, which can be included in agent prompts:

# Generate context file
tx context tx-abc123 --inject

# Use in agent prompt
claude "Read .tx/context.md for relevant learnings, then work on task tx-abc123"

The generated file:

# Context for tx-abc123: Implement authentication

## Relevant Learnings

- Always hash passwords with bcrypt, never store plaintext
- Use JWT tokens with short expiry (15min) and refresh tokens
- Rate limit login attempts to prevent brute force attacks

Custom Retriever

You can plug in your own vector database (Pinecone, Weaviate, Chroma, etc.):

// my-retriever.ts
import { Layer, Effect } from "effect"
import { RetrieverService } from "@jamesaphoenix/tx-core"

export default Layer.succeed(RetrieverService, {
  search: (query, options) => Effect.gen(function* () {
    // Custom Pinecone/Weaviate/Chroma implementation
    return yield* myVectorSearch(query, options)
  }),
  isAvailable: () => Effect.succeed(true)
})

Then use it:

tx context tx-abc123 --retriever ./my-retriever.ts

Agent Workflow

#!/bin/bash
# Start a task with full context

TASK=$(tx ready --json --limit 1 | jq -r '.[0].id')

# Generate context file
tx context "$TASK" --inject

# Run agent with context
claude "
Read .tx/context.md for relevant learnings.
Then run 'tx show $TASK' to see the task details.
Implement the task and mark it done with 'tx done $TASK'.
"

tx learning:add - Add new learnings
tx learning:search - Search learnings directly
tx ready - Get the next task to work on

tx context

On this page