Documentation · version contract
From config to record.
The public documentation targets the reviewed ax0s-memory 0.5.0 source snapshot. The CLI parser, MCP stdio startup, and recall serialization paths are implemented and test-covered. One recorded product round trip sits behind that.
- Documented version ax0s-memory 0.5.0
- Version contract Verified 2026-07-14
- Public package distribution Unavailable in this release
- Read surface snapshot Verified 2026-07-14
pip install 'ax0s-memory[cpu]'
Product access is reviewed by request. No public package or install command is claimed.
- A correction can become current while the prior record remains addressable.
- The reviewed read surface names seven read-only groups: recall/search, direct record reads, context composition, currentness and timeline inspection, fabric query, graph walk, and stats.
01 · Documentation map
Choose the contract behind the question.
Seven documents. Operations is published here. The rest are served from the live documentation tree.
- Start here Quickstart Install the CPU path, then inspect the recorded write, correction, current recall, history, and cleanup.
- Interface MCP The stdio entry point, the exact JSON configuration, and the documented tool names.
- Interface CLI python -m ax0s_memory invocations and the flags that matter.
- Mechanism Memory model Capture, retrieval, current-record defaults, and addressable superseded history.
- Record contract Provenance Source, agent, entrypoint, collection, role, tags, and the optional record fields.
- Boundary Operations What is documented today, and which operator procedures stay unpublished.
- Evidence state Evaluation Published methodology and rerun status, with no unsupported benchmark conclusions.
02 · HTTP surface
Three mounted surfaces. One visible gate.
One unified ASGI application mounts all three. The static documentation stays useful without starting the service.
Unified ASGI application
/api
REST facade
JSON endpoints for health, recall, remember, feedback, claims, sessions, tasks, record inspection, conflicts, timelines, maturity, and entity-fabric operations.
Auth: Per-principal bearer on non-health routes, then slug and capability checks.
/mcp
Streamable MCP over HTTP
The MCP tool surface on the streamable-HTTP transport, with a keepalive response at the same path.
Auth: Bearer-gated in the current unified application.
/sse
MCP over server-sent events
The same application mounts the SSE transport and its message path for clients that use it.
Auth: Bearer-gated in the current unified application.
| Route group | What it exposes | Boundary |
|---|---|---|
| GET /health GET /api/health | Liveness and configured-surface discovery. | Public Public. Stored slug names appear only for a resolvable bearer, filtered to that principal’s grants. |
| GET /api/recall /api/compose_context /api/timeline | Current recall, bounded context, and explicit history reads. | Bearer Bearer plus the applicable slug-read grant. |
| POST /api/remember /api/session/* /api/feedback | Record writes, session lifecycle, and use feedback. | Bearer Bearer plus the applicable slug-write grant. Input contracts fail visibly. |
| /mcp /sse | MCP transports backed by the same application and principal context. | Bearer Bearer-gated. Tool and slug checks still apply after authentication. |
03 · Auth boundary
Authentication is not record isolation.
Every line below renders from the security dossier, last reviewed 2026-08-25.
Current mode
Per-principal token.
Registry-issued bearer tokens resolve a principal. A token can carry expiry, revocation, slug grants, capability grants, and rate limits.
- Slug and capability grants implemented
- Token expiry implemented
- Token revocation implemented
- Default deny implemented for slug and tool dispatch
- Rate limits implemented per principal
A legacy shared-bearer path remains available only when the principal registry is absent or an explicit unexpired compatibility block remains.
Public exceptions
Health and discovery.
/health · /api/health · OAuth routes · well-known discovery
Public health does not expose the stored slug list.
No-auth connector mode
Separate, read-only, operator-enabled.
The current unified app bearer-gates its MCP and ChatGPT routes. A no-auth mode exists only through separate operator connector or deployment configuration. When enabled it exposes six read-only tools: memory recall, memory search, bounded context composition, local-root listing, allowlisted file discovery, and bounded allowlisted file reads; no write or command execution.
Not established
- Record-level authorization not established
- Hardened multi-tenant isolation not established
- Externally validated identity controls not established
Network exposure and transport security stay operator responsibilities.
04 · Error contract
Six codes, at a glance.
A failing request says which boundary it hit. Nothing is silently dropped.
- 400 Invalid or missing required input, with a structured body where documented.
- 401 Missing, invalid, expired, or revoked bearer.
- 403 The principal lacks the required grant or capability.
- 404 Unknown slug or record on a route that requires one.
- 409 Conflicting active claim lease.
- 422 Request-shape validation error.
05 · Static source counts
Definitions are breadth signals, not receipts.
Two of these three rows were superseded on the register. Their old totals are not restated here, and the rows stay readable.
| Area | Status | Checked |
|---|---|---|
| HTTP surface test definitions A historical static source-count artifact exists, but no current public test total or passing-run receipt is claimed. Source revision, counting rule, and run evidence are not published as a current passing receipt. | Superseded | 2026-07-14 |
| Audit helper test definitions Ten static audit-helper tests are defined for log helpers, recording, record round-trip, and CLI behavior. This narrow count does not establish broad access-event coverage, tamper evidence, a current passing run, or coverage percentage. | Verified 2026-07-14 | 2026-07-14 |
| Rust research engine test definitions A historical static source-count artifact exists, but no current public test total or passing-run receipt is claimed. Source revision, counting rule, and run evidence are not published as a current passing receipt. | Superseded | 2026-07-14 |
Version contract