This section provides complete documentation for all MemMachine API interfaces. The API Reference covers REST endpoints, protocol specifications, and client SDK interfaces for integrating with MemMachine's memory management system.
Scope: This page provides an overview of the API architecture, conventions, and organization. For detailed specifications, see the following child pages:
memmachine-client package@memmachine/client packageFor configuration file formats and environment variables, see Configuration Reference.
MemMachine exposes multiple API interfaces to accommodate different integration patterns. All interfaces provide access to the same underlying memory management system but differ in protocol and abstraction level docs/api_reference/intro.mdx7-46
The following diagram bridges high-level API concepts to the specific code entities that implement them, from the entry-point routers down to the core logic.
MemMachine API Architecture
Sources: docs/openapi.json8-12 docs/api_reference/intro.mdx30-44 packages/server/src/memmachine_server/server/api_v2/router.py94-222 packages/server/src/memmachine_server/server/api_v2/config_router.py39-45 docs/tools/generate_openapi.py18
The REST API uses a tag-based organization system defined in the OpenAPI specification docs/openapi.json13-50
| Tag | Endpoint Prefix | Purpose |
|---|---|---|
| Projects | /api/v2/projects | Lifecycle management for isolated memory namespaces docs/openapi.json27-29 |
| Memories | /api/v2/memories | Core operations for episodic and semantic ingestion docs/openapi.json23-25 |
| Configuration | /api/v2/config | System overview and memory subsystem configuration docs/openapi.json15-17 |
| Resources | /api/v2/config/resources | Embedder, LLM, and reranker lifecycle management docs/openapi.json31-33 |
| Semantic Memory: Sets | /api/v2/memories/semantic/set | Set type and ID lifecycle docs/openapi.json43-45 |
| Semantic Memory: Features | /api/v2/memories/semantic/feature | Individual semantic feature CRUD docs/openapi.json39-41 |
| System | /health, /metrics | Infrastructure, health, and observability docs/openapi.json47-49 |
Sources: docs/openapi.json13-50 packages/server/src/memmachine_server/server/api_v2/router.py97-222
MemMachine follows REST conventions for HTTP methods and response codes. Most write operations use POST or PUT with request bodies validated by the server docs/openapi.json51-152
| Method | Usage | Success Code |
|---|---|---|
GET | Retrieve configuration, status, or lists | 200 OK |
POST | Create resources or execute searches | 200 OK or 201 Created |
PUT | Update configuration or memory settings | 200 OK |
DELETE | Remove resources | 204 No Content |
Sources: docs/openapi.json52-152 packages/server/src/memmachine_server/server/api_v2/router.py97-222
All request and response bodies are validated using Pydantic models. The server and client rely on a "Shared Spec" architecture (found in memmachine_common.api.spec) to ensure consistent data validation across the network boundary docs/api_reference/python/server.mdx10-12
Data Flow and Validation
Sources: docs/api_reference/python/server.mdx11-23 packages/server/src/memmachine_server/server/api_v2/router.py8-64
The complete OpenAPI 3.1.0 specification is available at docs/openapi.json. It defines the structure of all endpoints, including authentication requirements and resource lifecycle states docs/openapi.json1-7
Key features of the spec:
ready, failed, or pending docs/openapi.json58HTTPValidationError responses for invalid request bodies docs/openapi.json103-112Sources: docs/openapi.json1-152 packages/server/src/memmachine_server/server/api_v2/config_router.py73-97
Projects are isolated namespaces identified by an org_id and project_id. This isolation ensures that memories from one project cannot be accessed by another docs/openapi.json6
Memory operations target two subsystems:
Sources: packages/server/src/memmachine_server/server/api_v2/router.py97-222 docs/api_reference/python/server.mdx27-40
The configuration API manages the lifecycle of AI resources. Users can add new embedders or LLMs at runtime and then point the memory systems to use these new resources via the ConfigService packages/server/src/memmachine_server/server/api_v2/config_router.py33-42
Key endpoints:
GET /api/v2/config: Returns a comprehensive view of all resources and their initialization status docs/openapi.json52-73PUT /api/v2/config/memory: Updates the active resource references for episodic or semantic subsystems docs/openapi.json74-115Sources: docs/openapi.json52-152 packages/server/src/memmachine_server/server/api_v2/config_router.py48-97
MemMachine provides official SDKs to simplify integration across different environments. For details, see Python Client SDK and TypeScript Client SDK.
Sources: docs/api_reference/intro.mdx7-46
Refresh this wiki