aimee exposes two versioned HTTP surfaces:
aimee-server /v1for clients, browsers, personal memory, private code, sessions, agents, tools, workflows, config, and OpenAI/Anthropic-compatible ingress;aimee-kb /v1for shared memory, documents, shared code, retrieval, curation, and KB administration.
Server is usable without KB. Its ordinary memory operations default to "store":"user";
"store":"kb" selects the optional shared service. This selector chooses the owner before scope
filtering. A project, working directory, missing ID, or owner outage never changes the selected
store. See Server and KB and the memory contract.
The generated references are authoritative:
- A stable route is prefixed with
/v1and has a stable operation ID. - New routes, optional request fields, and response fields may be added within v1.
- Clients must ignore unknown response fields.
- A breaking request or response change uses a new major prefix with an overlap period.
/v1/internal/*, explicitly experimental operations, browser proxy routes, and diagnostic fields are not public compatibility promises.
The generic POST /v1/rpc endpoint is retired. Use named operations.
Local clients use the server Unix socket. Remote clients use HTTPS. KB traffic is HTTP inside a declared deployment boundary or HTTPS across hosts.
JSON is the normal body format. Upload routes accept bounded raw or multipart content as described by their OpenAPI operation. Streaming routes declare their framing in the generated reference.
Every response has a status code. Errors return a small JSON object with a stable machine signal;
human wording may change. When present, X-Request-ID ties the response to logs and downstream
calls.
Use cursors where an operation exposes pagination. Do not infer numeric offsets.
| Caller | Authentication |
|---|---|
| local thin client | Unix-socket filesystem ownership |
| remote thin client | TLS pin plus bearer or mTLS client identity |
| browser | authenticated web session and CSRF protection |
| server → KB | configured service bearer and TLS where required |
| workflow → resource plane | supervised local peer and narrow internal route |
Authentication identifies the principal. Each route then checks capabilities, scope, and write tier. The shared bearer is read-only; writes use a KB-signed identity and exact subject grant.
Send remote bearer credentials as:
Authorization: Bearer <token>Do not put tokens in query strings.
Memory placement is explicit: Server accepts instance-local user scope; KB accepts global, workspace, and project scopes and rejects user-memory scope. KB document access has its own principal and membership rules. Each operation takes scope from its typed fields and authenticated context. A numeric ID alone does not grant access or identify which store owns it.
Remote writes are split into data and full authority. Data covers memory, documents, and index ingestion. Full also covers runner and workspace mutation. The route descriptor declares the class for each operation.
File commands from a thin client upload bytes. A server route must never interpret a client path as a local path.
Use the documented health, version, capability, and OpenAPI operations for feature detection. Do not derive server capability from a version string alone.
The running service may serve its OpenAPI document. CI checks route descriptors, handlers, and specs
for drift. make docs-gen-check checks the human reference.
SDKs are generated from OpenAPI for C, C++, C#, Go, Java, Python, Rust, and TypeScript. They are build artifacts, not hand-maintained clients.
scripts/gen-sdks.sh
scripts/gen-sdks.sh python go
make -C src sdk-parity-check
make -C src api-conformance-checkThe generator and toolchain requirements live in scripts/gen-sdks.sh. Run live SDK smoke tests
against the deployment before publishing an SDK package.
The shared-memory event bus is an intra-daemon module contract. It does not accept remote clients,
replace route authorization, or expose capture files over /v1. A future external bus adapter still
needs its own admission and public compatibility contract.