memeX exposes a FastAPI-served HTTP daemon at 127.0.0.1:7777 by default. This page documents every endpoint. The OpenAPI spec is also auto-generated at /openapi.json and a Swagger UI is mounted at /docs.
Auth
The daemon authenticates every non-/health endpoint with a bearer token.
- On first run the daemon generates a random token at
<data_dir>/daemon.tokenwith mode0600(POSIX) or default user-restricted ACLs (Windows). The CLI read it automatically. - Override with
MEMEX_AUTH_TOKEN=<your-token>to use your own. - When binding to a non-loopback address (
0.0.0.0, etc.) the daemon refuses to start withoutMEMEX_AUTH_TOKEN— fail loud, not silent.
GET /recall?q=auth HTTP/1.1
Host: 127.0.0.1:7777
Authorization: Bearer <token><data_dir> defaults to:
| OS | Path |
|---|---|
| Linux | ~/.local/share/memex/ |
| macOS | ~/Library/Application Support/memex/ |
| Windows | %LOCALAPPDATA%\Quefly\memex\ |
Override with MEMEX_DATA_DIR=/your/path.
Health & system
GET /health
Liveness probe. Public — no auth required.
{ "ok": true, "version": "1.0.0", "tier": 1 }GET /system
Daemon footprint: RAM, CPU, uptime, DB size breakdown.
GET /logs?limit=100
Last N lines from the daemon’s in-memory log ring buffer.
Memory operations
POST /nodes
Add a concept node.
{
"name": "Use Postgres over MySQL",
"description": "JSONB usage drove the decision.",
"kind": "decision",
"source": "human",
"confidence": 1.0,
"verification": null,
"metadata": {}
}kind ∈ pattern | decision | constraint | module | endpoint | person | fact | opinion | question | rejected | approach.
Returns the created node with a generated id.
GET /nodes/{id}
Fetch a single concept by id.
POST /edges
Create a typed edge between two concepts.
{
"from_id": "abc123",
"to_id": "def456",
"kind": "supersedes",
"source": "agent"
}GET /recall?q=<query>&budget=2000&kind=&expand=1
Hybrid retrieval. Returns a subgraph bounded by budget tokens.
{
"nodes": [...],
"edges": [...],
"tokens_used": 1842,
"strategy": "hybrid",
"degraded": false,
"degraded_reason": null
}degraded is true when the embed tier is unavailable and recall fell back to BM25-only — your client should surface this rather than silently accept weaker recall.
Episodic events
POST /observe
Emit an episodic event.
{
"kind": "decision",
"actor": "agent",
"payload": { "what": "chose Postgres", "why": "JSONB" }
}GET /progress?actor=<actor>&since=<iso8601>
Activity summary — concepts added, recalls performed, validations attested.
Skills
GET /skills
List builtin skill bundles.
POST /skills/install
Install a builtin skill into the engine.
{ "name": "core-validations" }POST /validate
Return the structured approach + checks + examples for a skill. Auto-emits an episodic event for the validation.
{ "skill": "secure-subprocess", "actor": "agent" }Response:
{
"ok": true,
"skill": "secure-subprocess",
"approach": "Pass arguments as a list, never as a string. Avoid shell=True...",
"checks": ["arguments are a list (not a single string)", "shell=False"],
"examples_good": [...],
"examples_bad": [...]
}Upstreams (MCP gateway)
GET /upstreams
List configured upstream MCP servers and their connection status. Token values are scrubbed from the response.
POST /upstreams
Install an upstream from the curated catalog or as a custom entry.
DELETE /upstreams/{name}
Remove an upstream.
OpenAPI
curl http://127.0.0.1:7777/openapi.jsonGenerate a typed client in any language with openapi-generator, oapi-codegen, etc.