Memory Schema API

The API allows for the dynamic inspection of existing memory schemas. This includes listing all defined schemas, retrieving their full structure, and querying metadata such as creation date, version, and associated embedding models. For example, an engineer can programmatically discover that a CustomerInteraction schema contains fields for session_id, user_query, agent_response, and a sentiment_score vector.

• Key Operation: GET /schemas or GET /schemas/{schema_name}
• Use Case: Automating documentation generation or validating system state during deployment.

Engineers can define new memory structures on-the-fly without manual database configuration. This involves specifying field names, data types (e.g., string, integer, float, vector), and constraints. The API validates the schema definition and initializes the necessary indexes in the underlying storage layer (e.g., vector database, knowledge graph).

• Key Operation: POST /schemas with a JSON payload.
• Example Payload: Defines a ProductSpec schema with a description text field and a technical_embedding vector field of 768 dimensions.

As agent capabilities evolve, their memory structures must adapt. The API supports schema versioning and provides mechanisms for safe migration. This includes adding non-breaking fields, deprecating old fields, and executing data transformation scripts. It ensures backward compatibility and prevents data corruption during updates.

• Key Feature: Immutable schema versions with migration history.
• Use Case: Adding a new confidence_score field to an existing DecisionLog schema without disrupting live agents.

A schema defines which embedding model is used to generate vector representations for specific fields. The API allows for the association of a model (e.g., text-embedding-3-small, a fine-tuned in-house model) with vector fields. It may also handle model lifecycle hooks, such as triggering re-embedding if the model is updated.

• Key Function: Links semantic search capability directly to data structure.
• Technical Detail: Schema stores the model's name, dimensionality, and normalization requirements for the vector index.

Beyond basic structure, the schema API configures how data is indexed for efficient retrieval. This includes setting the distance metric (e.g., cosine similarity, Euclidean distance) for vector fields and specifying secondary indexes for filtering (e.g., on timestamp or categorical fields). It defines the blueprint for the Memory Query Planner.

• Performance Impact: Directly influences memory latency and throughput.
• Example: Configuring a HNSW (Hierarchical Navigable Small World) index for approximate nearest neighbor search on a conversation_embedding field.

Schema definitions are foundational for memory observability. The API exposes schema metadata to telemetry systems, enabling rich, context-aware logging and monitoring. For instance, memory metrics like query latency can be broken down by schema, and memory traces can be annotated with the schema version involved in a request.

• Observability Link: Enables OpenTelemetry for Memory instrumentation at the schema level.
• Use Case: Triggering a memory alert when error rates spike for writes to a specific, mission-critical schema.

The primary interface for semantic search and retrieval from a memory store. While a Schema API defines the structure, the Query API is used to execute searches against that structure. It accepts a query (often as text or an embedding vector) and returns ranked results based on similarity scores. Key operations include:

• Vector similarity search: Finding memories closest to a query embedding.
• Hybrid search: Combining vector search with keyword or metadata filters.
• Filtering: Constraining results by metadata fields defined in the schema.

The programmatic interface for creating, updating, and deleting records in an agentic memory store. It is the counterpart to the Query API and operates on the data structures defined by the Schema API. A robust Write API handles:

• Upsert operations: Creating or updating a memory record in a single call.
• Batch ingestion: Efficiently writing large volumes of memories.
• Atomic updates: Ensuring data consistency for complex modifications.
• Embedding generation: Often integrates with an embedding model to automatically generate vector representations for stored text.

The automated collection and transmission of operational data from a memory system. While a Schema API allows inspection of what data can be stored, telemetry reveals how the system is performing. Critical telemetry signals include:

• System metrics: Query latency, throughput, and error rates.
• Resource utilization: CPU, memory (RAM), and I/O usage of the memory backend.
• Business-level metrics: Cache hit rate, recall@K for retrieval accuracy.
• Integration with standards: Often implemented using OpenTelemetry for unified observability.

An immutable, chronological log of all access and modification events within a memory system. It provides a security and compliance complement to the structural definition offered by a Schema API. A comprehensive audit trail logs:

• Data lifecycle events: Creation, updates, deletions, and access (reads).
• Schema modifications: Changes to the memory structure itself via the Schema API.
• User and agent context: Who or which agent performed the action.
• Compliance data: Essential for regulated environments (e.g., GDPR, HIPAA) to demonstrate data governance.

A diagnostic API endpoint or procedure that verifies the operational status of a memory system and its dependencies. It is a foundational observability primitive. A health check typically tests:

• Connectivity: Can the application reach the memory database (e.g., vector DB)?
• Latency: Is response time within acceptable SLA bounds?
• Dependency status: Are required services (embedding models, auth services) available?
• Schema validity: Are the defined schemas loadable and internally consistent?