External Clients (HTTP, Ollama, Qdrant)

Relevant source files

The following files were used as context for generating this wiki page:

• services/memory-api/src/clients/http.ts
• services/memory-api/src/clients/ollama.ts
• services/memory-api/src/clients/qdrant.ts
• services/memory-api/test/clients.test.ts
• services/memory-api/src/ingest/ingest.ts
• README.md
• services/memory-api/README.md
• docker-compose.yml

External clients provide the interface between the memory-api service and the core infrastructure components of the Nyansa stack. These clients handle communication with Ollama for generating text embeddings and Qdrant for vector storage and semantic retrieval. The implementation relies on a shared HTTP utility to perform authenticated requests over the internal Docker network.

These clients implement the Embedder and VectorStore interfaces, abstracting the underlying API calls from the core ingestion and search logic. This architecture allows the memory-api to process Obsidian notes and perform RAG (Retrieval-Augmented Generation) tasks using local AI models.

Sources: services/memory-api/README.md, README.md:41-55, services/memory-api/src/ingest/ingest.ts:50-55

Architecture and Data Flow

The memory-api communicates with external services exclusively through these client implementations. All traffic remains within the internal nyansa Docker network.

Ollama Client (OllamaEmbedder)

The OllamaEmbedder class manages text embedding generation. It sends text chunks to Ollama and receives high-dimensional vectors. The client uses the nomic-embed-text model by default and applies specific prefixes required by the model for document indexing and query searching.

Key Features

• Batch Processing: It groups multiple text chunks into batches to optimize network throughput and processing speed.
• Prefixing: It automatically adds search_document: to documents being indexed and search_query: to search strings.
• Error Handling: It converts HTTP errors or malformed responses into UpstreamError types for consistent error reporting.

Sources: services/memory-api/src/clients/ollama.ts:25-50, services/memory-api/test/clients.test.ts:38-50, services/memory-api/README.md:105-110

Interaction Flow

Qdrant Client (QdrantStore)

The QdrantStore class manages the vector database. It handles collection lifecycle, point upserts (storing embeddings with metadata), and semantic search queries.

Data Management Functions

Function	Description	Source
ensureCollection	Verifies collection existence and creates it with Cosine distance and keyword indexes for path and tags.	qdrant.ts:29-50
listIndexedNotes	Scans the collection for existing notes by filtering for chunks with chunk_index: 0.	qdrant.ts:68-85
upsertChunks	Writes vector points and their associated payloads to the database.	qdrant.ts:88-98
search	Executes semantic similarity searches with optional tag filtering and score thresholds.	qdrant.ts:114-135
deleteNote	Removes points associated with a specific file path, supporting partial tail deletion during updates.	qdrant.ts:101-112

Metadata Payload

The client stores a comprehensive payload with every vector, enabling filtered search and citation generation:

• path: Note file path.
• title: Extracted note title.
• tags: Deduplicated, lower-cased tags.
• text: The raw text content of the chunk.
• note_hash: SHA-256 of the source file to track changes.

Sources: services/memory-api/src/clients/qdrant.ts:140-160, services/memory-api/src/domain.ts:41-55

HTTP Utility and Configuration

All clients utilize a standardized fetch-based utility for network communication. This ensures uniform authentication and error behavior across the service.

Authentication and Connectivity

Clients are configured via environment variables and require specific tokens for internal communication.

Variable	Target Service	Purpose
OLLAMA_URL	Ollama	Base API endpoint (default: http://nyansa-ollama:11434)
QDRANT_URL	Qdrant	Base API endpoint (default: http://nyansa-qdrant:6333)
QDRANT_API_KEY	Qdrant	Required header: api-key
MEMORY_API_TOKEN	memory-api	Required header: Authorization: Bearer <token>

Sources: docker-compose.yml:258-270, services/memory-api/src/clients/qdrant.ts:20-25, services/memory-api/README.md:120-135

Implementation Detail: Shared Request Logic

// From services/memory-api/src/clients/http.ts
async request<T>(path: string, options: RequestInit = {}): Promise<T> {
  const url = new URL(path, this.baseUrl).toString();
  const response = await this.fetchFn(url, {
    ...options,
    headers: { ...this.defaultHeaders, ...options.headers },
  });
  if (!response.ok) {
    throw new UpstreamError(this.serviceName, await response.text(), response.status);
  }
  return response.json();
}

Sources: services/memory-api/src/clients/http.ts:25-40, services/memory-api/test/clients.test.ts:70-80

Conclusion

The external clients module encapsulates all infrastructure-specific details for Ollama and Qdrant. By centralizing request prefixing, batching, and schema management in these clients, the Nyansa project maintains a clean separation between high-level RAG logic and the low-level API requirements of its AI components.