API Reference

MCP tools

MemStrata exposes three MCP tools to connected AI clients. These are the tools your AI tool calls when MemStrata is connected as an MCP server.

---

context_query

Returns a compressed, dependency-aware context slice for a given query.

Input schema:

{
  "query": "string — natural language or symbol name",
  "max_tokens": "integer — optional, default 4096",
  "include_tests": "boolean — optional, default false"
}

Output:

{
  "context": "string — compressed context slice",
  "tokens": "integer — token count of the slice",
  "baseline_tokens": "integer — what naive RAG would have sent",
  "sources": ["array of file paths included in the slice"]
}

Example:

// Request
{ "query": "AuthService.login and its callers", "max_tokens": 2048 }

// Response
{
  "context": "// src/auth/AuthService.ts\n...",
  "tokens": 1843,
  "baseline_tokens": 4211,
  "sources": ["src/auth/AuthService.ts", "src/routes/auth.ts", "src/middleware/session.ts"]
}

---

index_status

Returns the current state of the codebase index.

Input schema: none (no parameters)

Output:

{
  "project": "string — absolute path of indexed project",
  "files_indexed": "integer",
  "last_indexed": "ISO 8601 timestamp",
  "index_size_mb": "number",
  "status": "ready | indexing | stale | error"
}

---

savings_summary

Returns token and dollar savings accumulated in the current session.

Input schema: none

Output:

{
  "session_tokens_saved": "integer",
  "session_dollar_saved": "number",
  "cycle_tokens_saved": "integer",
  "cycle_dollar_saved": "number",
  "provider_rate_per_token": "number",
  "recall": "number — 0–1",
  "precision": "number — 0–1"
}

---

HTTP endpoints

The MemStrata harness listens on http://localhost:8080 (default port). All endpoints are localhost-only.

---

GET /health

Returns harness status.

{ "status": "ok", "version": "5.2.x", "uptime_seconds": 3600 }

---

GET /status

Returns index status and session stats (same data as index_status MCP tool).

---

POST /v1/chat/completions (OpenAI-compatible)

The harness proxy endpoint for tools using --openai-api-base. Forwards requests to your configured provider after compressing the context.

Headers: Authorization: Bearer <your-provider-api-key>

Accepts the standard OpenAI chat/completions request body. Returns the provider’s response unchanged (the compression happens to the request before forwarding).

---

POST /anthropic/v1/messages (Anthropic-compatible)

Same as above but uses the Anthropic Messages API format. Use this when proxying Claude models via Anthropic’s SDK.

---

GET /mcp

MCP server endpoint (SSE transport). Used by MCP clients that connect via HTTP rather than stdio.

---

GET /metrics

Returns Prometheus-format metrics for the harness (token counts, latency histograms, error rates).

memstrata_tokens_sent_total{project="my-project"} 142840
memstrata_tokens_saved_total{project="my-project"} 62310
memstrata_requests_total{status="200"} 1204

---

Provider hints config

MemStrata uses a provider hints file to configure cost rates and model-specific settings. Default location: ~/memstrata/providers.json.

{
  "providers": {
    "anthropic": {
      "models": {
        "claude-3-7-sonnet-20250219": {
          "input_cost_per_mtok": 3.00,
          "output_cost_per_mtok": 15.00
        }
      }
    },
    "openai": {
      "models": {
        "gpt-4o": {
          "input_cost_per_mtok": 2.50,
          "output_cost_per_mtok": 10.00
        }
      }
    },
    "ollama": {
      "models": {
        "*": {
          "input_cost_per_mtok": 0.0,
          "output_cost_per_mtok": 0.0
        }
      }
    }
  }
}

Use memstrata config set provider-rate <model> <rate> to update rates from the CLI.