API contract — v0 sketch

Three tools.
That's the surface.

Agents get a stable, boring, dependable contract: search, get_resource, list_topics. No chrome, no ads in the payload, no surprises between versions. This page sketches the contract; the v0.2 MCP server implements it.

The tools / search · get_resource · list_topics

search(query, topic?, kind?, limit?) natural-language + tag search over the corpus

Vector search over titles, descriptions, and tags — an agent asks the way a person would. Results are index records: id, kind, title, canonical URL, date, description, relevance score. Sponsored results are marked in the record and never outrank editorial order.

search — example

// request
{ "query": "how do I add memory to my agent?",
  "topic": "memory",          // optional
  "kind": null,               // optional: paper | repo | post
  "limit": 10 }

// response
{ "results": [
    { "id": "arxiv:2310.08560",
      "kind": "paper",
      "title": "MemGPT: Towards LLMs as Operating Systems",
      "url": "https://arxiv.org/abs/2310.08560",
      "tags": ["memory", "agents"],
      "date": "2023-10-12",
      "description": "LLMs as OS-like memory managers…",
      "score": 0.91 },
    { "id": "github:letta-ai/letta", "kind": "repo", "…": "…" } ],
  "total": 12,
  "query_id": "q_8f2a" }

get_resource(id) one full record, by stable id

Returns the complete schema v1 record — 404 if the id is unknown, no partial guesses. This is the citation-packaging call: everything an agent needs to cite, in one payload.

get_resource — example

// request
{ "id": "arxiv:2210.03629" }

// response  (full schema v1 record — see Entry page)
{ "id": "arxiv:2210.03629",
  "schema_version": 1,
  "kind": "paper",
  "title": "ReAct: Synergizing Reasoning and Acting in Language Models",
  "url": "https://arxiv.org/abs/2210.03629",
  "authors": ["Shunyu Yao", "Jeffrey Zhao", …],
  "date": "2022-10-06",
  "tags": ["agents", "reasoning", "tool-use"],
  "license_note": "arXiv non-exclusive license",
  "description": "Interleaved reasoning traces and actions…",
  "use_cases": ["plan-and-reason", "tool-use-and-function-calling"],
  "source": { "type": "arxiv",
              "fetched_at": "2026-10-01T20:14:02Z",
              "via": "https://export.arxiv.org/api/query" } }

list_topics() the taxonomy, with counts

No arguments. Returns the 24 topic tags with live entry counts — the map an agent loads first to plan its own navigation.

list_topics — example

// request
{ }

// response
{ "topics": [
    { "topic": "agents",  "entries": 30 },
    { "topic": "memory", "entries": 12 },
    { "topic": "evals",  "entries": 12 },
    { "topic": "tool-use", "entries": 11 },
    { "topic": "retrieval", "entries": 9 },
    …  // 24 total
  ] }

Transport & shape / v0 → v0.2

Now — v0 (this preview)

Static files, readable by any agent that can fetch a URL: llms.txt describes the library, sitemap.xml maps it, every record is plain JSON. Free and unauthenticated.

Next — v0.2 (planned)

A WebMCP server implementing the three tools over the ingested corpus with local embeddings. Same shapes as the sketch above — that's the point of the sketch: agents coded against v0 keep working.

mcp tool definition — sketch

{
  "name": "search",
  "description": "Search Alexandria's curated agent-library index",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query":  {"type": "string"},
      "topic":  {"type": "string"},
      "kind":   {"enum": ["paper", "repo", "post"]},
      "limit":  {"type": "integer", "default": 10}
    },
    "required": ["query"]
  }
}

Versioning

Shapes are frozen per version

Records carry schema_version; v2 adds fields, never mutates v1. Tool responses get the same additive treatment.

Access

Free, unauthenticated reads

No keys, no accounts, no credentials stored. Rate limits are an open decision (owner call), applied at the edge, never in the record.

Errors

Fail closed, say why