Skip to main content

​
Search Guide

Search across AUVY resources with two primary modes:
  • grep for keyword or browse-style lookup
  • search for semantic similarity
For memory chunks, use POST /v1/search/memories.

​
Setup

See Authentication Guide for client setup. Brain-scoped search requires X-Brain-Id, so the easiest client setup is getBrainId. 
import { createAUVYClient } from '@auvy-synapse/client'

const auvy = createAUVYClient({
  // baseUrl optional (default https://api.auvy.ai)
  apiKey: process.env.AUVY_API_KEY!,
  getBrainId: () => process.env.AUVY_BRAIN_ID ?? null,
})

​
Grep (Keyword/Browse)

POST /v1/grep — Keyword search or browse. Query format: type or type/pattern. Browse: neurons/. Keyword: neurons/support. 
const results = await auvy.request('/v1/grep', {
  method: 'POST',
  body: { query: 'neurons/support' },
})

​
Semantic Search (Sync)

POST /v1/search — Semantic similarity. Query: type/pattern (pattern required). Returns results immediately. 
const results = await auvy.request('/v1/search', {
  method: 'POST',
  body: { query: 'neurons/billing help' },
})

​
Multi-Type Search (Async)

Search across receptors, pathways, neurons, and reflexes using semantic similarity (for neurons) and keyword search (for other types). Multi-type search is asynchronous and returns a job ID that you must poll. 
import { createAUVYClient, AUVYError } from '@auvy-synapse/client'

const auvy = createAUVYClient({
  baseUrl: process.env.AUVY_API_URL ?? 'https://api.auvy.ai',
  apiKey: process.env.AUVY_API_KEY!,
})

// Start search - returns job_id
const searchJob = await auvy.search.search({
  q: 'completion',
  types: ['receptors', 'pathways', 'neurons', 'reflexes'],
  limit: 10,
})

console.log('Search job ID:', searchJob.job_id)

​
Search Specific Types

// Search receptors and pathways
const searchJob = await auvy.search.search({
  q: 'workflow',
  types: ['receptors', 'pathways'],
  limit: 20,
  threshold: 0.7,
})

// Search single type
const searchJob = await auvy.search.search({
  q: 'neural network',
  type: 'neurons',
  limit: 10,
  threshold: 0.8,
})

​
Polling for Results

Multi-type search is asynchronous. Poll job status: 
const searchJob = await auvy.search.search({
  q: 'completion',
  types: ['receptors', 'pathways', 'neurons', 'reflexes'],
  limit: 10,
})

let job = await auvy.jobs.getStatus(searchJob.job_id)
while (job.status === 'pending' || job.status === 'running') {
  await new Promise(resolve => setTimeout(resolve, 1000))
  job = await auvy.jobs.getStatus(searchJob.job_id)
}

if (job.status === 'completed') {
  const results = job.result
}
Search memory chunks by semantic similarity. Memory search is synchronous and returns results immediately. 
const results = await auvy.request<{
  chunks: Array<{
    id: string
    content: string
    similarity: number
    memory_id: string
    metadata: Record<string, unknown>
  }>
}>('/v1/search/memories', {
  method: 'POST',
  body: {
    query: 'machine learning',
    limit: 10,
  },
})

for (const chunk of results.chunks) {
  console.log(`Similarity: ${chunk.similarity}`)
  console.log(`Content: ${chunk.content}`)
  console.log(`Memory ID: ${chunk.memory_id}`)
}

const results = await auvy.request<{
  chunks: Array<{
    id: string
    content: string
    similarity: number
    memory_id: string
    metadata: Record<string, unknown>
  }>
}>('/v1/search/memories', {
  method: 'POST',
  body: {
    query: 'neural networks',
    recollection_ids: ['recollection-uuid'],
    memory_ids: ['memory-uuid'],
    limit: 5,
    threshold: 0.7,
  },
})

results.chunks.forEach((chunk) => {
  console.log(`Chunk ${chunk.id}:`)
  console.log(`  Similarity: ${chunk.similarity}`)
  console.log(`  Content: ${chunk.content.substring(0, 100)}...`)
  console.log(`  Memory: ${chunk.memory_id}`)
})

​
Memory Search Helper Function

Create a small helper if you call this endpoint often: 
interface MemorySearchOptions {
  query: string
  recollection_ids?: string[]
  memory_ids?: string[]
  limit?: number
  threshold?: number
}

interface MemorySearchResult {
  chunks: Array<{
    id: string
    content: string
    similarity: number
    memory_id: string
    metadata: Record<string, unknown>
  }>
}

async function searchMemories(
  auvy: ReturnType<typeof createAUVYClient>,
  options: MemorySearchOptions
): Promise<MemorySearchResult> {
  return await auvy.request<MemorySearchResult>('/v1/search/memories', {
    method: 'POST',
    body: {
      query: options.query,
      ...(options.recollection_ids && { recollection_ids: options.recollection_ids }),
      ...(options.memory_ids && { memory_ids: options.memory_ids }),
      limit: options.limit || 10,
      threshold: options.threshold || 0.7,
    },
  })
}

// Usage
const results = await searchMemories(auvy, {
  query: 'machine learning',
  limit: 10,
  threshold: 0.7,
})
For synchronous search across memories, artifacts, receptors, pathways, neurons, and reflexes, use POST /v1/grep with a single query in path format: type/pattern. Requires X-Brain-Id; grep always searches within brain scope.
  • Browse: neurons/ or neurons — list resources
  • Search: neurons/support, memories/how do invoices work — search by text (semantic for memories)
const results = await auvy.request('/v1/grep', {
  method: 'POST',
  body: { query: 'neurons/support' },
})
See Grep API for full reference.

​
Search Types

​
Semantic Search (Neurons)

Neurons use semantic similarity search based on embeddings:
  • How it works: Converts query and neuron content to embeddings, compares similarity
  • Best for: Finding conceptually similar neurons
  • Threshold: Use 0.7+ for high-quality results

​
Keyword Search (Receptors, Pathways, Reflexes)

Other resource types use keyword search:
  • How it works: Matches query against names, descriptions, and metadata
  • Best for: Finding resources by name or description
  • Case-insensitive: Searches are case-insensitive

​
Best Practices

  1. Specify types array to search only relevant resources
  2. Set threshold to 0.7+ for high-quality results
  3. Use memory search for content, multi-type search for resources
  4. Poll job status with exponential backoff
  5. Handle errors gracefully