Knowledge, messaging, and events

AetherFS includes several non-filesystem data surfaces that are critical for real workflows.

Knowledge cache

The session cache is a public key/value workflow surface.

Key routes include:

• GET /v1/sessions/{sessionId}/cache/{key}
• PUT /v1/sessions/{sessionId}/cache/{key}
• DELETE /v1/sessions/{sessionId}/cache/{key}
• GET /v1/sessions/{sessionId}/cache/{key}/exists
• GET /v1/sessions/{sessionId}/cache/{key}/metadata
• POST /v1/sessions/{sessionId}/cache/{key}/compare-and-set
• GET /v1/sessions/{sessionId}/cache/keys
• GET /v1/sessions/{sessionId}/cache/stats
• POST /v1/sessions/{sessionId}/cache/batch-get
• POST /v1/sessions/{sessionId}/cache/batch-set
• POST /v1/sessions/{sessionId}/cache/batch-delete
• POST /v1/sessions/{sessionId}/cache/delete-by-prefix

Use the cache for structured workflow data that should be retrieved by key rather than stored as a file.

Good uses:

• Summaries.
• Derived metadata.
• Tool outputs.
• Workflow coordination state.

Compare-and-set support

The cache API includes compare-and-set style operations.

Use them when multiple writers may update the same key and you need deterministic conflict control.

Message bus

Bus routes include:

• GET /v1/sessions/{sessionId}/bus
• POST /v1/sessions/{sessionId}/bus:publish

Use the bus for event-like communication attached to a session.

Good uses:

• Progress updates.
• Tool notifications.
• Live activity streams.
• Human/agent coordination.

Session events

The public contract also includes:

• /v1/sessions/{sessionId}/events

Use events when you want a session activity or change stream without storing that information as file content.

Design guidance

Choose the right surface deliberately:

• Use the filesystem for user content.
• Use the cache for keyed structured data.
• Use the bus for event-style communication.
• Use events for activity-oriented integration.

That separation keeps product behavior easier to understand and easier to automate.