API Reference

CMK exposes a REST API on the configured port. All endpoints accept and return JSON. Authentication is optional and configured via API keys.

Base URL: http://localhost:7749. All paths below are relative to this base.

GET/api/memories

List all memories. Supports filtering by gate, scope, and pagination.

Response

{
  "memories": [
    {
      "id": "mem_abc123",
      "content": "User prefers VS Code",
      "gate": "behavioral",
      "scope": "user",
      "confidence": 92,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "total": 147
}

Parameters

gatestring?Filter by gate type

scopestring?Filter by scope (user, project, global)

limitint?Max results (default 50)

offsetint?Pagination offset (default 0)

POST/api/memories

Create a new memory. The gate is auto-classified if not provided.

Request body

{
  "content": "We use PostgreSQL 16 for all services",
  "gate": "epistemic",
  "scope": "project"
}

Response

{
  "id": "mem_def456",
  "content": "We use PostgreSQL 16 for all services",
  "gate": "epistemic",
  "scope": "project",
  "confidence": 85,
  "created_at": "2026-02-14T09:00:00Z"
}

POST/api/search

Semantic search across memories. Returns ranked results with confidence scores.

Request body

{
  "query": "preferred database",
  "limit": 5,
  "gate": null,
  "min_confidence": 50
}

Response

{
  "results": [
    {
      "id": "mem_def456",
      "content": "We use PostgreSQL 16 for all services",
      "gate": "epistemic",
      "confidence": 85,
      "similarity": 0.94
    }
  ]
}

GET/api/identity

Retrieve the current identity synthesis document. This is a generated summary of the user based on stored memories.

Response

{
  "identity": "You are a senior TypeScript developer...",
  "updated_at": "2026-02-14T08:00:00Z",
  "memory_count": 47
}

PUT/api/identity

Replace the identity document with a new synthesis.

Request body

{
  "identity": "Updated identity text..."
}

Response

{
  "identity": "Updated identity text...",
  "updated_at": "2026-02-14T09:30:00Z"
}

PATCH/api/memories/{id}

Update a specific memory. Supports editing content, gate, scope, and confidence.

Request body

{
  "content": "Updated memory content",
  "confidence": 95
}

Response

{
  "id": "mem_abc123",
  "content": "Updated memory content",
  "confidence": 95,
  "updated_at": "2026-02-14T10:00:00Z"
}

Parameters

idstringMemory ID (path parameter)

POST/api/memories/{id}/pin

Pin a memory to prevent decay. Pinned memories maintain their confidence indefinitely.

Response

{
  "id": "mem_abc123",
  "pinned": true
}

Parameters

idstringMemory ID (path parameter)

DELETE/api/memories/{id}/pin

Unpin a memory. It will resume normal decay behavior from its current confidence.

Response

{
  "id": "mem_abc123",
  "pinned": false
}

Parameters

idstringMemory ID (path parameter)

GET/api/stats

Get memory statistics: total count, breakdown by gate, average confidence, storage usage.

Response

{
  "total": 147,
  "by_gate": {
    "behavioral": 42,
    "relational": 18,
    "epistemic": 53,
    "promissory": 21,
    "correction": 13
  },
  "avg_confidence": 78.4,
  "storage_bytes": 2457600
}

POST/api/reflect

Trigger a reflection cycle. CMK reviews recent memories, resolves contradictions, and updates the identity document.

Response

{
  "resolved": 3,
  "decayed": 7,
  "identity_updated": true
}

GET/api/mode

Get the current storage mode (local or cloud).

Response

{
  "mode": "local",
  "storage": "sqlite",
  "embeddings": "fastembed"
}

GET/api/keys

List all API keys. Keys are masked in the response.

Response

{
  "keys": [
    {
      "id": "key_001",
      "name": "development",
      "prefix": "cmk_dev_****",
      "created_at": "2026-01-10T12:00:00Z"
    }
  ]
}

POST/api/keys

Create a new API key. The full key is only returned once at creation time.

Request body

{
  "name": "production"
}

Response

{
  "id": "key_002",
  "name": "production",
  "key": "cmk_prod_abc123def456",
  "created_at": "2026-02-14T10:00:00Z"
}

DELETE/api/keys/{key_id}

Revoke an API key. This action is irreversible.

Response

{
  "deleted": true
}

Parameters

key_idstringAPI key ID (path parameter)