§ /docs — mcp · rest · admin

The interaction surface,
every endpoint.

Seven MCP tools. A REST surface for core operations and administration. Entra OAuth, API-key, and local profiles share the same memory engine.

transport · MCP · streamable HTTPrest · FastAPI · OpenAPI 3.1auth · Entra OAuth · API key · local

§ jump toMCP tools REST mirror Admin Errors

§ 01 — MCP TOOLS

Seven 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" | "local" | "copilot",
  task_hint?: "debug" | "architecture" | "compliance" | "writing" | "chat"
}

`borg_learn` — record

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

// arguments
{
  content: string,
  source: string,
  namespace: string,
  metadata?: object
}

`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"
}

`borg_get_episode` — fetch

Fetch the complete stored body and metadata for an episode returned by recall.

// arguments
{ episode_id: string }

`borg_forget` — delete

Soft-delete an episode, fact, entity, or procedure. Episode deletion can cascade to derived memory.

// arguments
{
  target_type: "episode" | "fact" | "entity" | "procedure",
  target_id: string, namespace: string,
  reason?: string, cascade?: boolean
}

`borg_guard` — risk check

Check a proposed action against known failures, constraints, and related memory.

// arguments
{
  action: string, namespace: string,
  files?: string[], proposed_change?: string,
  task_hint?: string
}

`borg_project_summary` — summarize

Build deterministic Markdown from active decisions, constraints, recent work, procedures, conflicts, and failed attempts.

// arguments
{ namespace: string }

§ 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	/api/episodes/{episode_id}	`borg_get_episode`
POST	/api/forget	`borg_forget`
POST	/api/guard	`borg_guard`
GET	/api/admin/namespaces/{namespace}/summary	`borg_project_summary`
GET	/health	Liveness · returns engine + worker status
GET	/docs	Deployment Swagger UI when `BORG_ENABLE_DOCS=true`

§ 03 — ADMIN

Inspect the pipeline,
drive the worker.

The admin surface exposes queue state, graph records, audit traces, project summaries, snapshots, and extraction cost.

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
GET /api/admin/episodes
GET /api/admin/audit

Control

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

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

§ 04 — ERRORS

Predictable failures,
diagnostic bodies.

REST failures are JSON. Authentication, authorization, validation, missing resources, and rate limits have distinct status codes that clients can handle directly.

Status	Condition	Response behavior
401 / 403	Missing credentials / insufficient access	Entra, API-key, role, and namespace checks stay distinct.
404	Unknown namespace	Resource is absent, deleted, or outside the visible scope.
422	Request validation failed	FastAPI returns the invalid field path and validation message.
429	Rate-limited (default 60/min on learn)	Retry after `Retry-After` seconds.
503	Service or extraction dependency unavailable	Retry after the dependency or worker recovers.