Memory Query API

The API's defining feature is the ability to perform semantic search using vector similarity. Instead of matching exact keywords, it retrieves memories based on conceptual meaning.

• Query Embedding: The input query is converted into a high-dimensional vector embedding using the same model that encoded the stored memories.
• Similarity Calculation: The API computes a similarity score (e.g., cosine similarity, dot product) between the query vector and all stored memory vectors.
• Top-K Retrieval: Returns the k most semantically relevant memory items, ranked by their similarity score. This allows agents to find contextually related information even without precise keyword recall.

Beyond semantic search, a robust API supports hybrid search by combining vector similarity with structured filters on metadata.

• Filterable Fields: Queries can include constraints on attached metadata like timestamp, source, agent_id, session_id, or custom tags (e.g., priority: high).
• Boolean Logic: Supports operators (AND, OR, NOT) and comparisons (>, <, ==) to narrow results. Example: find memories about 'budget' from the last 7 days where source='email'.
• Performance: Applying filters before or during the vector search (pre-filtering or post-filtering) is a critical implementation detail that affects latency and recall accuracy.

The API exposes standardized endpoints (typically REST or gRPC) with well-defined request/response schemas.

• Core Endpoint: A /query or /search endpoint accepting a JSON payload.
• Request Parameters: Includes the query_text (or pre-computed query_vector), limit (top-k), filter object, and optional score_threshold.
• Response Schema: Returns a list of memory objects, each containing the retrieved content, metadata, the computed similarity score, and the unique memory ID for subsequent reference or updates.
• Consistency: Adheres to idempotent and stateless principles where possible, with the state managed by the underlying memory store.

The Memory Query API is the foundational retrieval component in a RAG pipeline. Its performance directly determines the quality and relevance of context provided to a Large Language Model.

• Context Assembly: Retrieved memories are formatted into a context window (e.g., via a prompt template) and passed to the LLM for generation.
• Latency Critical Path: Query latency is a major factor in overall agent response time. Optimizations include caching, approximate nearest neighbor (ANN) indexes, and efficient embedding model inference.
• Recall vs. Precision: The API's configuration (e.g., top-k value, score threshold) balances recall (finding all relevant items) against precision (ensuring returned items are relevant), which is tuned based on the agent's task.

For production systems, the API provides built-in observability features essential for debugging and performance tuning.

• Query Logging: Logs all queries with parameters, execution time, and number of results returned.
• Telemetry Export: Emits metrics like query latency, results count, and cache hit rate, often integrating with standards like OpenTelemetry.
• Traceability: Assigns a correlation ID to each query, propagating it through downstream systems to enable end-to-end tracing of how a specific memory influenced an agent's final action or response.

In multi-tenant or enterprise environments, the API enforces access control at the query level to ensure data isolation and privacy.

• Authentication/Authorization: Validates the identity of the querying agent or user and checks permissions.
• Query-Time Filtering: Automatically injects tenant or user-specific filters into every query (e.g., WHERE tenant_id = 'abc') to enforce data isolation. This is often implemented as a middleware layer.
• Audit Compliance: Logs query attempts for compliance with regulations (GDPR, HIPAA), linking access to specific identities and purposes, which feeds into the memory audit trail.

The programmatic interface for creating, updating, or deleting records within an agentic memory store. It is the complementary write operation to the Query API's read operation.

• CRUD Operations: Typically exposes create, update, and delete endpoints.
• Idempotency: Often designed to be idempotent to ensure reliable state updates in distributed systems.
• Data Validation: Enforces the memory's schema and may trigger embedding generation for new content.
• Example: A user profile agent calls the Write API to store a new customer interaction after a support call.

An interface for inspecting, creating, and modifying the data structure definitions (schemas) within an agentic memory store. It defines the 'shape' of the data that can be queried and written.

• Schema Definition: Specifies fields, data types, and whether a field should be indexed for semantic search.
• Dynamic Schemas: May allow for schema evolution without downtime.
• Integration Point: The Query API uses the schema to understand how to parse and execute filters on structured fields.
• Example: An engineer uses the Schema API to add a priority: integer field to an agent's task memory.

The automated collection, transmission, and analysis of operational data from an agentic memory system to monitor its health, performance, and behavior in real-time.

• Core Data: Includes metrics, traces, and logs.
• Purpose: Enables observability to answer questions about system state and performance.
• Tools: Often integrated with platforms like Prometheus for metrics and Jaeger for traces.
• Example: Telemetry data shows a spike in query latency, triggering an alert for investigation.

Quantitative measurements that track the performance, capacity, and health of an agentic memory system.

• Key Performance Indicators (KPIs):
  • Memory Latency: Query/Write response time (P95, P99).
  • Memory Throughput: Queries per second (QPS).
  • Memory Cache Hit Rate: Percentage of reads served from cache.
  • Memory Error Rate: Frequency of failed operations.
• Usage: Drives alerting, capacity planning, and performance tuning.
• Example: A dashboard tracks vector_search_latency_p99 to ensure it stays under a 100ms SLA.

A chronological, immutable log that records all access and modification events within an agentic memory system for security, compliance, and debugging.

• Recorded Events: Includes queries, writes, deletions, and schema changes.
• Essential Metadata: Timestamp, user/agent ID, correlation ID, and operation details.
• Compliance: Critical for frameworks like GDPR (right to be forgotten) and HIPAA (access logs).
• Forensics: Used to reconstruct events leading up to a system anomaly or data breach.

The application of the OpenTelemetry (OTel) standard to instrument agentic memory systems, generating unified traces, metrics, and logs.

• Standardization: Provides vendor-agnostic instrumentation for observability.
• Three Pillars:
  • Traces: End-to-end request lifecycle (e.g., a single query's journey).
  • Metrics: Aggregated numerical data (e.g., latency, error count).
  • Logs: Timestamped event records.
• Benefit: Allows engineers to correlate memory system performance with broader application performance using a shared correlation ID.