§ /docs — mcp · rest · admin

The interaction surface,
every endpoint.

Three MCP tools. A REST mirror for every one. A small set of admin endpoints for queues, snapshots, and traces. All open, none behind auth in the OSS release.

transport · MCP · streamable HTTPrest · FastAPI · OpenAPI 3.1auth · none · single-user

§ jump toMCP tools REST mirror Admin Errors

§ 01 — MCP TOOLS

Three tools,
explicit schemas.

Every MCP client invokes these by name. All take JSON arguments matching the schema below.

`borg_think` — compile

Classify the query, retrieve across strategies, rank on 4 dimensions, compile a token-budgeted context package.

// arguments
{
  query: string,
  namespace: string,
  model?: "claude" | "gpt" | "copilot",
  task_hint?: "debug" | "architecture" | "compliance" | "writing" | "chat",
  budget_tokens?: number
}

`borg_learn` — record

Store an episode. Extraction runs async so this returns in milliseconds and never blocks the agent loop.

// arguments
{
  content: string,
  source: "claude-code" | "codex" | "copilot" | "kiro" | "slack" | string,
  namespace: string,
  occurred_at?: ISO-8601,
  participants?: string[]
}

`borg_recall` — browse

Direct memory search without compilation. Raw episodes, facts, and procedures — for UI, audits, or the developer at the console.

// arguments
{
  query: string,
  namespace: string,
  memory_type?: "episodic" | "semantic" | "procedural" | "all",
  limit?: number
}

§ 02 — REST MIRROR

Same tools,
plain HTTP.

Not every upstream speaks MCP. The REST mirror gives you the same surface for webhooks, CI, ad-hoc scripts, or legacy apps.

Method	Path	Maps to
POST	/api/think	`borg_think`
POST	/api/learn	`borg_learn`
POST	/api/recall	`borg_recall`
GET	/health	Liveness · returns engine + worker status
GET	/docs	Swagger UI · full OpenAPI spec

§ 03 — ADMIN

Inspect the pipeline,
drive the worker.

The admin surface lets you observe the extraction queue, trigger snapshots, and audit exactly what went into the last compile.

Observability

// queue depth, running, errors, throughput
GET /api/admin/queue

// list recent entities / facts / procedures
GET /api/admin/entities
GET /api/admin/facts
GET /api/admin/procedures

Control

// force-process or requeue
POST /admin/process-episode
POST /admin/requeue-failed

// snapshot + cost
POST /admin/snapshot
GET /admin/cost-summary

§ 04 — ERRORS

Predictable failures,
diagnostic bodies.

Everything returns JSON. Every 4xx and 5xx includes a detail field and, where applicable, a hint with the exact next step.

Status	Condition	Hint body
400	Missing / malformed args	Invalid field enumerated with a JSON pointer.
404	Unknown namespace	Lists known namespaces within reason.
429	Rate-limited (default 60/min on learn)	Retry after `Retry-After` seconds.
503	Worker queue backed up > 1 min	Reads still served from last-good state.