API Reference

Complete API documentation for MoltBrain's worker service and MCP tools. Use these endpoints to integrate MoltBrain with your own applications or build custom integrations.

Worker Service API

Base URL: http://localhost:37777

GET /health

Health check endpoint to verify the worker service is running

curl http://localhost:37777/health

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "worker": "running"
}

GET /api/search

Semantic search across all memories using ChromaDB vector search

GET /api/search?q=authentication&limit=10

Query Parameters:

q - Search query (required)
limit - Max results (default: 10)
projectPath - Filter by project (optional)

Response:

{
  "results": [
    {
      "id": "obs_123",
      "content": "Use JWT tokens for authentication",
      "relevance": 0.92,
      "metadata": {}
    }
  ]
}

GET /api/timeline

Get chronological memory timeline for a project

GET /api/timeline?project=/Users/dev/my-app&days=7

Query Parameters:

project - Project path (required)
days - Number of days to include (default: 30)

POST /api/observations

Create a new observation in memory

POST /api/observations
Content-Type: application/json

{
  "sessionId": "session_123",
  "projectPath": "/Users/dev/my-app",
  "type": "learning",
  "content": "Use JWT for authentication",
  "metadata": {
    "files": ["auth.ts"],
    "tools": ["write_file"]
  }
}

Response:

{
  "id": "obs_123",
  "status": "created"
}

GET /api/stats

Get memory statistics and analytics

GET /api/stats?project=/Users/dev/my-app

Response:

{
  "totalObservations": 1250,
  "totalSessions": 45,
  "memorySize": "2.5MB",
  "oldestMemory": "2024-01-15T10:30:00Z"
}

MCP Tools

recall_context

Recall relevant context from memory for a given query. Combines SQLite and ChromaDB queries.

{
  "query": "authentication setup",
  "limit": 50,
  "projectPath": "/Users/dev/my-app"
}

Returns top N most relevant memories based on semantic similarity and recency.

search_memories

Semantic search across all memories using vector similarity

{
  "query": "JWT token structure",
  "limit": 10
}

Uses ChromaDB for semantic search. Finds memories by meaning, not just keywords.

save_memory

Manually save an observation to memory

{
  "type": "decision",
  "content": "Use PostgreSQL for data storage",
  "metadata": {
    "files": ["database.ts"],
    "tools": ["write_file"]
  }
}

Stores observation in both SQLite (structured) and ChromaDB (semantic) for optimal retrieval.

Configuration

Configure MoltBrain through environment variables or configuration files. All settings have sensible defaults.

Environment Variables

Configuration Options

{
  "MOLTBRAIN_WORKER_PORT": 37777,
  "MOLTBRAIN_CONTEXT_OBSERVATIONS": 50,
  "MOLTBRAIN_PROVIDER": "claude",
  "MOLTBRAIN_PRUNE_DAYS": 0,
  "MOLTBRAIN_THEME": "system",
  "MOLTBRAIN_LOG_LEVEL": "info"
}

MOLTBRAIN_WORKER_PORTPort for the worker service (default: 37777)

MOLTBRAIN_CONTEXT_OBSERVATIONSNumber of memories to inject per session (default: 50)

MOLTBRAIN_PROVIDERLLM provider for embeddings: claude, openai (default: claude)

MOLTBRAIN_PRUNE_DAYSDays before pruning old memories (0 = never, default: 0)

Error Handling

All API endpoints return standard HTTP status codes:

200 OK - Request successful
400 Bad Request - Invalid parameters
404 Not Found - Resource not found
500 Internal Server Error - Server error

Error response format:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}