Skip to main content

API Reference

iLAB Memory ships a single facade — ILabMemory — and three transports that map to it 1:1. Pick the transport that matches your runtime; the semantics are identical across all of them.

Library (Python)

Embedded Python. Import ILabMemory, point it at a SQLite file, call methods directly. Lowest latency, primary surface.

HTTP REST

ilab-memory serve — FastAPI on port 7437. Use this when memory lives in a separate process or when consumers are written in another language. OpenAPI spec: download openapi.json and load it into Swagger UI / Redoc / Postman.

MCP stdio

ilab-memory mcp — FastMCP server. Use this when an IDE (Claude Code, Cursor) or an autonomous agent needs the 8 tools surfaced over the Model Context Protocol.

When to use which​

SurfaceUse when…Avoid when…
LibraryYou own the Python process. You want zero IPC overhead and direct objects (Observation, SessionStartResponse).Multiple processes or non-Python consumers need to share the same memory.
HTTP RESTA separate service (Node, Go, browser) reads/writes memory. You want OpenAPI tooling, rate limits, and CORS out of the box.A single Python script is the only consumer (use the library, save the network hop).
MCP stdioAn IDE or agent host (Claude Code, Claude Desktop, Cursor) needs to call memory as tools. The 8 tools come pre-described — no glue code.You need ad-hoc REST-style access from arbitrary clients (use HTTP).
note

All three surfaces serialize the same Pydantic models from ilab_memory.core.models. This is Braess #6 — the wire format is single-source-of-truth. A SaveResult over HTTP, MCP, or in-process Python has the exact same fields and validation rules.

What's in this section​

  • Library — full reference for the ILabMemory class: constructor, from_path factory, and all 8 facade methods (mem_session_start, mem_save, mem_search, …).
  • HTTP API — the full OpenAPI spec is published at /docs/openapi.json. Load it in Swagger UI, Redoc, or Postman to explore interactively. The library section above documents the same Pydantic models that HTTP serializes.
  • MCP Server — setup snippets for Claude Code, Claude Desktop, and Cursor. The tool docstrings travel with the server, so the agent doesn't need an external prompt to use them.