v3 API surface

Shipped in v3-alpha (Beta). Most of these endpoints are live; interfaces may still change before 3.0 stable. The Scalar reference reflects what your running server exposes. See Roadmap for remaining milestones.

Base path

/v1

Most v3 endpoints live under /v1/memory/*, with sessions under /v1/session/* and self-editing under /v1/self/*. Existing v2 endpoints (/v1/facts, /v1/decisions, etc.) remain unchanged for backward compatibility.

Session lifecycle

POST   /v1/session                            Start session
POST   /v1/session/:id/turns                  Add turn
POST   /v1/session/:id/pin                    Pin a turn for collapse
POST   /v1/session/:id/scratch                Update scratchpad
POST   /v1/session/:id/collapse               Collapse session → knowledge
DELETE /v1/session/:id                        Discard session

→ Session memory + collapse

Recall (tiered)

POST   /v1/memory/recall                      Full hybrid search
POST   /v1/memory/recall/hot                  Tier-1 only (<5ms)
POST   /v1/memory/recall/unified              KB + Memory blended
POST   /v1/memory/recall/explain              Recall + "why this result" BOM

→ Three-tier retrieval

Knowledge units CRUD

POST   /v1/memory/facts                       Create (conflict detection)
GET    /v1/memory/facts/:id                   Read
PATCH  /v1/memory/facts/:id                   Update (creates revision)
DELETE /v1/memory/facts/:id                   Soft-delete (archive)
POST   /v1/memory/decisions                   Record decision
POST   /v1/memory/strategies                  Store behavioral pattern
POST   /v1/memory/workflows                   Store multi-step recipe
POST   /v1/memory/skills                      Store reusable capability

→ Cognitive primitives

Entities & graph

POST   /v1/memory/entities                    Create / findOrCreate
GET    /v1/memory/entities/:id/graph          Subgraph around entity
POST   /v1/memory/relations                   Create relation (binary or hyperedge)
POST   /v1/memory/relations/traverse          Graph traversal query

→ Hypergraph relations

Episodes & timeline

POST   /v1/memory/episodes                    Create
GET    /v1/memory/episodes/:id/timeline       Timeline view
GET    /v1/memory/timeline                    Global timeline (filtered)

→ Delta-encoded episodes

Tasks & events

POST   /v1/memory/tasks                       Create task
PATCH  /v1/memory/tasks/:id                   Update state
GET    /v1/memory/tasks                       List (filtered by agent/status)
POST   /v1/memory/tasks/:id/delegate          Delegate to another agent

POST   /v1/memory/events                      Record event
GET    /v1/memory/events                      Query (time range)

→ Tasks & events

CoT distillation

POST   /v1/memory/reasoning/resolve           Check cache before execution
POST   /v1/memory/reasoning/record            Store successful chain
POST   /v1/memory/reasoning/feedback          Report outcome of cached result

→ CoT distillation engine

Self-edit

POST   /v1/self/edit                          Agent edits own memory
POST   /v1/self/reflect                       Trigger self-reflection
GET    /v1/self/profile                        Computed profile summary

→ Self-editing memory

Procedural memory

POST   /v1/memory/procedural/optimize         Submit trajectory for evolution
GET    /v1/memory/procedural/prompt/:agent    Current evolved prompt

→ Procedural memory

Governance

GET    /v1/memory/governance/worth            Memory worth scores
POST   /v1/memory/governance/gate             Manually gate/ungate consolidation
GET    /v1/memory/governance/drift            Memory drift report

→ Memory Worth · Consolidation Gate

Health & admin

GET    /v1/memory/health                      Health snapshot
GET    /v1/memory/health/history              Historical drift
POST   /v1/memory/admin/consolidate           Manual trigger (with gate check)
GET    /v1/memory/admin/stats                 Usage statistics
POST   /v1/memory/admin/export                Full memory export
POST   /v1/memory/admin/import                Bulk import

Federation

POST   /v1/memory/federation/sync             Push/pull with remote instance
GET    /v1/memory/federation/peers            List connected instances
POST   /v1/memory/federation/resolve          Resolve cross-instance conflict

→ Federation protocol · Trust-anchor consensus