Skip to main content

​
Search Context

Semantic search across all your context blocks.

​
Request Body

​
query
string
required
Natural language search query
​
sessions
array
Session IDs to search. Omit to search all sessions.
​
tags
array
Filter by tags
​
types
array
Filter by block types: conversation, file, diff, note, etc.
​
limit
number
default:"10"
Maximum results
​
threshold
number
default:"0.7"
Minimum similarity score (0-1)
curl -X POST https://api.runtools.ai/v1/aip/search \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "When did we decide to use PostgreSQL instead of MongoDB?",
    "sessions": ["sess_abc123", "sess_def456"],
    "tags": ["database", "architecture"],
    "limit": 5
  }'

{
  "data": {
    "results": [
      {
        "blockId": "blk_db001",
        "sessionId": "sess_abc123",
        "sessionName": "Backend Architecture",
        "type": "conversation",
        "score": 0.94,
        "snippet": "After considering both options, we decided PostgreSQL would be better for our relational data needs...",
        "tags": ["database", "postgresql", "architecture-decision"],
        "createdAt": "2026-01-15T10:00:00Z"
      },
      {
        "blockId": "blk_db002",
        "sessionId": "sess_abc123",
        "sessionName": "Backend Architecture",
        "type": "note",
        "score": 0.87,
        "snippet": "Decision: Use PostgreSQL for main database, Redis for caching",
        "tags": ["database", "decision"],
        "createdAt": "2026-01-15T11:00:00Z"
      }
    ],
    "totalMatches": 2,
    "searchTime": 45
  }
}

​
Search Tips

​
Effective Queries

Ask questions naturally:
  • “When did we decide to use JWT?”
  • “What authentication approach did we choose?”
  • “How does the payment flow work?”

​
Filtering

Narrow results with tags and session filters: 
// Search only in auth-related context
const results = await hub.search({
  query: 'token expiration',
  tags: ['authentication', 'security'],
});

// Search recent project only
const results = await hub.search({
  query: 'database schema',
  sessions: ['sess_current_project'],
});

​
Result Scoring

Results are scored by semantic similarity:
ScoreMeaning
0.9+Highly relevant
0.8-0.9Relevant
0.7-0.8Somewhat relevant
< 0.7Filtered out (below threshold)

​
Get Preferences

Get learned user preferences extracted from conversations. 
curl https://api.runtools.ai/v1/aip/preferences \
  -H "X-API-Key: rt_live_xxx"

{
  "data": {
    "preferences": {
      "coding_style": "functional, immutable, TypeScript",
      "formatting": "const over let, explicit return types, 2-space indent",
      "frameworks": "React, Next.js, Tailwind",
      "testing": "Vitest, React Testing Library",
      "architecture": "modular, clean architecture, dependency injection",
      "communication": "concise, technical, show code examples"
    },
    "extractedFrom": 89,
    "lastUpdated": "2026-01-21T10:00:00Z"
  }
}

​
Update Preferences

Manually update or override preferences.

​
Request Body

​
preferences
object
required
Preferences to update (merged with existing)
curl -X PATCH https://api.runtools.ai/v1/aip/preferences \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "testing": "Jest, Cypress",
      "error_handling": "explicit try/catch, custom error classes"
    }
  }'

{
  "data": {
    "updated": true,
    "preferences": {
      "coding_style": "functional, immutable, TypeScript",
      "testing": "Jest, Cypress",
      "error_handling": "explicit try/catch, custom error classes"
    }
  }
}