Server Beta REST V1 API

Relevant source files

• docs/api.md
• src/server/mcp/recall-mcp-server.ts
• src/server/routes/v1/ServerV1PostgresRoutes.ts
• src/storage/postgres/data-deletion.ts
• src/storage/postgres/index.ts
• tests/server/connect-keys.test.ts
• tests/server/data-deletion.test.ts
• tests/server/mcp/recall-mcp-server.test.ts
• tests/server/runtime/server-mcp-http-routes.test.ts

The Server Beta REST V1 API is the modern, scalable interface for the claude-mem persistent memory system. Unlike the legacy worker API, the V1 API is designed for multi-tenant, production-grade deployments using Postgres for storage and BullMQ/Redis (or Valkey) for asynchronous processing src/server/routes/v1/ServerV1PostgresRoutes.ts33-35 It is mounted under the /v1 prefix and provides high-performance endpoints for session management, event recording, and memory retrieval docs/api.md3-5

Authentication and Security

The API supports two primary authentication modes, with the server-beta runtime utilizing Postgres-backed authentication logic src/server/routes/v1/ServerV1PostgresRoutes.ts153-162

API Key Mode

In production environments, api-key mode is the standard docs/api.md31

• Headers: The API requires Authorization: Bearer <key> docs/api.md31
• Scopes: Access is gated by a scope-based system. memories:read is required for GET/search routes, while memories:write is required for POST/DELETE routes src/server/routes/v1/ServerV1PostgresRoutes.ts153-162
• Key Minting: Write-scoped keys can mint new read-only keys for MCP clients via POST /v1/keys docs/api.md57-60

Local Dev Mode

This mode allows unauthenticated access for development, typically originating from the loopback interface src/server/routes/v1/ServerV1PostgresRoutes.ts59

• Bypass Conditions: Enabled via the allowLocalDevBypass option in the route configuration src/server/routes/v1/ServerV1PostgresRoutes.ts155-162

Sources: src/server/routes/v1/ServerV1PostgresRoutes.ts153-162 docs/api.md31-32 tests/server/connect-keys.test.ts56-60

---

API Entity Relationship

The following diagram bridges Natural Language concepts to the Postgres-backed Code Entities and the underlying data structures defined in the repository layer.

Diagram: Server Beta Entity Mapping

Sources: src/storage/postgres/index.ts32-44 src/storage/postgres/data-deletion.ts18-19 src/server/routes/v1/ServerV1PostgresRoutes.ts8-20

---

Endpoint Reference

Session and Project Management

Sessions track the lifecycle of an AI agent's interaction with a project.

Method	Endpoint	Description
POST	/v1/sessions/start	Creates a new session within a project docs/api.md12
POST	/v1/sessions/:id/end	Marks a session as finished and triggers summarization docs/api.md13
GET	/v1/projects	Lists all projects available to the authenticated team docs/api.md9
DELETE	/v1/projects/:id/memory	Purges all observations and events from a project while keeping the project shell src/storage/postgres/data-deletion.ts35-42

Event Pipeline and Generation

Events are the raw inputs (tool uses, assistant messages) from which memories are extracted.

• Generation Control: POST /v1/events accepts a generate query flag. If false, the event is recorded but no extraction job is queued src/server/routes/v1/ServerV1PostgresRoutes.ts73-76
• Wait Semantics: Using ?wait=true causes the request to poll for the terminal status of the resulting PostgresObservationGenerationJob for up to 30 seconds src/server/routes/v1/ServerV1PostgresRoutes.ts81-87
• Batch Ingestion: POST /v1/events/batch allows multiple events to be recorded in a single call docs/api.md16

Diagram: Request Flow & Generation Semantics

Sources: src/server/routes/v1/ServerV1PostgresRoutes.ts89-116 src/server/routes/v1/ServerV1PostgresRoutes.ts123-131 docs/api.md81-93

Memory and Search

The V1 API provides structured access to generated observations and search capabilities.

Method	Endpoint	Description
POST	/v1/search	Performs full-text search over memories docs/api.md21
POST	/v1/context	Returns observations and a concatenated context string for prompt injection docs/api.md22
DELETE	/v1/memories/:id	Deletes a single specific observation src/storage/postgres/data-deletion.ts22-28

Remote MCP Endpoint

The /v1/mcp endpoint implements the Model Context Protocol over streamable HTTP src/server/routes/v1/ServerV1PostgresRoutes.ts46-50

• Tools: Exposes search, context, and recent tools to MCP clients like Claude Code src/server/mcp/recall-mcp-server.ts39-80
• Security: Read-only access bound to the API key's team and project scope src/server/mcp/recall-mcp-server.ts11-14

---

Implementation Details

Usage Metering and Quotas

The V1 routes include optional middleware for production guardrails docs/api.md33-47

• Rate Limiting: CLAUDE_MEM_RATE_LIMIT_PER_MIN restricts requests per API key docs/api.md38-39
• Monthly Caps: Quotas can be enforced for total requests or provider tokens per team docs/api.md40-44
• Usage Tracking: GET /v1/usage returns current month totals for requests and observations docs/api.md49-53

Data Deletion (Forget)

The PostgresDataDeletionRepository implements the "right-to-erasure" path src/storage/postgres/data-deletion.ts3-6

• Cascading Deletes: Deleting an observation or event automatically removes associated observation_sources src/storage/postgres/data-deletion.ts5-6
• Project Purge: The purgeProjectMemory method clears observations, jobs, events, and sessions within a single transaction while preserving the project shell src/storage/postgres/data-deletion.ts35-53

Sources: src/server/routes/v1/ServerV1PostgresRoutes.ts29-31 src/storage/postgres/data-deletion.ts1-55 docs/api.md33-53