REST API
Generated from the OpenAPI specification for Meaning Memory 3.20.0. Start the server with meaning-memory serve. Every endpoint except the health probes needs a bearer token in the Authorization header.
Each endpoint is marked stable or preview. Preview endpoints may change between releases.
Memories
Section titled “Memories”GET /v1/memories
Section titled “GET /v1/memories”Query Memories · stable
Query active entries with text-search + filters.
tenant_id resolved per-request from bearer token. PG backend scopes WHERE writer_tenant_id; FB single-tenant per instance.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
q |
query | string | Substring (case-insensitive) full-text query. | |
since |
query | string | Only entries with date >= YYYY-MM-DD. | |
min_sig |
query | number | ||
limit |
query | integer | ||
sort_by |
query | string | sig_desc | date_desc | |
include_decay |
query | boolean | When true, each response entry includes a decay_score field computed from the default v3.10 decay config. Default false to preserve the existing response shape + avoid a per-entry compute cost when not requested. |
|
writer_agent_id |
query | string | Filter to a specific writer agent within the tenant. Powers the dashboard agent-picker. Tenant scope is still enforced via bearer; this is an additional intra-tenant filter. | |
memory_stage |
query | string | Stage filter. Omitted (default) EXCLUDES working-stage entries; ‘working’ returns only the working buffer (explicit opt-in); ‘long_term’ only long-term; ‘any’ disables the filter. |
Responses: 200 Successful Response, 401 Unauthorized, 422 Validation Error
POST /v1/memories
Section titled “POST /v1/memories”Append Memory · stable
Append a new memory entry to the active ledger.
Adds optional Idempotency-Key
HTTP header for safe POST retries. Wire surface on top of
storage layer.
tenant_id resolved per-request from the bearer token’s tenant binding. Entry’s writer_tenant_id is enforced to match the resolved tenant — caller-supplied writer_tenant_id mismatching the token’s tenant is rejected with 400.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key |
header | string | Optional client-supplied idempotency key for safe POST retries (Stripe-style convention). When present: replay with same key + same payload returns the cached response with X-Idempotent-Replay: true header; same key + different payload returns 422 idempotency_conflict. Requires PG backend (FileBackend returns 501). TTL default 7 days. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
category |
string | Category name. Core categories (always available): deadline, decision, fact, lesson, project, preference, content, brand, episode. Customer-extensible categories (dark-launch in v3.8.1) are declared via [categories.extensions] in the TOML config; see PARTNER_ONBOARDING.md Appendix A. | |
date |
string | Entry date YYYY-MM-DD; default = today (UTC). | |
divergence_kind |
string | Structured enum companion to divergence_rationale, typed as an OpenAPI closed enum (12 values). Pair (kind, rationale) — kind enables dashboard filtering, rationale explains. Pure annotation; no scoring impact. | |
divergence_rationale |
string | One-sentence operator-UX explanation for why sig_self and sig_external diverge. Free-text up to 1024 chars. Pure narrative — does not affect retrieval scoring. Pairs with divergence_kind below for analytics. | |
last_invoked_at |
string | ISO-8601 timestamp of last successful capability invocation. Procedural-only — ignored for memory_type='semantic' and memory_type='episodic'. Used by the C2 compilation pipeline for the 12-month decay floor when the procedural section overflows its 25% budget cap. None for newly-added capabilities. |
|
memory_type |
string | Storage taxonomy for the memory. One of: 'semantic' (default — facts, relationships, preferences; sig-weighted, decays with budget pressure), 'episodic' (events, observations; time-stamped, recency-weighted), 'procedural' (capabilities, skills, how-to; exempt from sig-trimming, emitted in dedicated Capabilities section). Procedural memories solve the failure mode where a sig-tracked capability gets compiled out under budget pressure even though the agent still needs it. Pair procedural with last_invoked_at when the capability has been verified-working recently. |
|
party |
string | Subject the memory is about (for forget_subject scope). | |
pinned |
boolean | True = protected from budget trimming. | |
run_id |
string | Run identifier (for grouping into Sessions). | |
sig |
number | Merged significance [0.0, 1.0]. Legacy single-axis field; still the primary value used by retrieval ranking. When sig_self and sig_external are both supplied, callers may choose to set sig = max(sig_self, sig_external) or use a merge policy of their choice. Required for backwards-compat. | |
sig_external |
number | Objective external utility [0.0, 1.0] — how important the memory is for outward task performance, audit, or shared context. Optional. Pairs with sig_self for phenomenological-vs-utility divergence analysis (see query_divergent in the Python SDK). | |
sig_self |
number | Phenomenological self-significance [0.0, 1.0] — how important the writing agent perceives the memory to be for its own identity / continuity. Anchored to Conway & Pleydell-Pearce 2000 Self-Memory System. Optional. Persists to PostgresBackend; FileBackend serialization ships in v3.8.2. | |
source |
string | Source identifier (e.g., ‘consolidation-pipeline’). | |
source_agent |
string | Writing agent identifier. | |
text |
string | yes | Memory entry text. |
writer_role |
string | Sig RBAC writer role. One of {'admin', 'agent', 'human', 'system'} or None. NULL is treated as 'agent' (strictest cap, 0.7) by the engine — defensive default for legacy / unattributed writes. Drives the cap applied to sig_self via meaning_memory.sig_rbac.enforce_sig_self_cap(); clamp events emit a sig_self_clamped row to the mm_sig_events ledger so importance-inflation attempts are recoverable via the mm_provenance MCP tool. Pair with MM_SIG_SELF_CAPS_OVERRIDE env JSON for per-deployment cap customization. |
Responses: 201 Successful Response, 400 ValidationError, 401 Missing/invalid token, 409 DuplicateEntryError, 422 Idempotency conflict — same Idempotency-Key was previously used with a different payload, 501 Idempotency-Key supplied but current backend does not support idempotency storage (PG backend required)
GET /v1/memories/{mem_id}
Section titled “GET /v1/memories/{mem_id}”Get Entry · stable
Fetch a single entry by mem_id.
tenant_id resolved per-request; PG SELECT scoped
to (writer_tenant_id, mem_id). Cross-tenant access returns
404 (entry exists but is in a different tenant — indistinguishable
from “not found” to defeat tenant enumeration).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
mem_id |
path | string | yes | Memory ID — 8-char legacy or 16-char current hex |
include_decay |
query | boolean | When true, the response includes a decay_score field computed from the default v3.10 decay config. |
Responses: 200 Successful Response, 401 Unauthorized, 404 EntryNotFoundError, 422 Validation Error
Feedback
Section titled “Feedback”POST /v1/memories/{mem_id}/feedback
Section titled “POST /v1/memories/{mem_id}/feedback”Feedback · preview
Adjust an entry’s significance with caller attribution.
tenant_id resolved per-request; mutation scoped
via PG’s WHERE (writer_tenant_id, mem_id) filter. Cross-tenant mutation returns 404 (defeats enumeration).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
mem_id |
path | string | yes |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
actor |
string | yes | Caller identity (logged in events). |
new_sig |
number | yes | |
reason |
string | yes | Why the sig is being adjusted. |
Responses: 200 Successful Response, 400 Bad Request, 401 Unauthorized, 404 Not Found, 422 Validation Error
Session synthesis
Section titled “Session synthesis”POST /v1/sessions/synthesize
Section titled “POST /v1/sessions/synthesize”Synthesize Session · preview
Cross-Session synthesis. Deterministic mode by default —
operators wanting LLM-driven narrative output should use the
Python SDK synthesize_sessions with their own llm_client.
tenant_id resolved per-request from bearer
token. The legacy request body field req.tenant_id is
preserved for backward compatibility but ignored — the bearer
token IS the tenant binding. To assist operator migration we
log a warning if the body field is set and differs from the
token-resolved tenant. A future v3.11 deprecation cycle removes
the body field entirely.
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
max_entries_per_session |
integer | ||
max_sessions |
integer | ||
mem_ids |
array of string | Filter: include only these mem_ids. | |
query |
string | yes | Natural-language question. |
run_id |
string | Filter: source_agent or source matches. | |
sessions_by |
string | run_id|date|week. | |
since |
string | Filter: entries with date >= YYYY-MM-DD. | |
tenant_id |
string | Tenant scope for active-entry read. Default ‘default’ matches PostgresBackend default. Pass empty string for cross-tenant admin reads. x-mm-maturity: stable. |
Responses: 200 Successful Response, 400 Empty filter result, 401 Unauthorized, 422 Validation Error
POST /v1/agent/describe-self
Section titled “POST /v1/agent/describe-self”Describe Self · preview
Identity coherence — deterministic self-description grounded in the agent’s highest-sig memories. LLM-driven mode requires the Python SDK directly.
tenant_id resolved per-request; sourced memories are scoped to the resolved tenant’s row set.
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
agent_name |
string | Optional header for the system prompt. | |
budget_chars |
integer | ||
budget_lines |
integer | ||
prompt |
string | Question. Default: identity prompt. | |
sig_pinned |
number |
Responses: 200 Successful Response, 401 Unauthorized, 422 Validation Error
Health
Section titled “Health”GET /healthz
Section titled “GET /healthz”Kubernetes liveness probe · stable
Returns 200 if the process is alive and responsive. NO auth required (kubelet convention). Does NOT touch backend storage. Accepts both GET and HEAD (cloud LBs default to HEAD).
Responses: 200 Successful Response
GET /readyz
Section titled “GET /readyz”Kubernetes readiness probe · stable
Returns 200 if the pod can serve traffic, 503 otherwise. NO auth required (kubelet convention). Checks backend reachability, alembic head match (PG only), and SIGTERM drain flag. Accepts both GET and HEAD.
Responses: 200 Successful Response, 503 Service Unavailable
GET /v1/health
Section titled “GET /v1/health”Health · stable
Lightweight health check — backend reachability + entry count + alembic head.
For full schema-and-services diagnostic, use meaning-memory doctor.
Responses: 200 Successful Response, 401 Unauthorized, 422 Validation Error
GET /v1/health-score
Section titled “GET /v1/health-score”Customer dashboard primitive — single-number health score for graphing. · preview
Returns the Memory Health Score in [0.0, 1.0] with documented interpretation thresholds. Direction: higher is healthier (1.0 = perfect, 0.0 = critically degraded). Set ?breakdown=true for per-sub-score detail.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
breakdown |
query | boolean | When true, include the per-sub-score breakdown in the response. Default false keeps the high-frequency polling payload small. | |
writer_agent_id |
query | string | Optional intra-tenant filter: scope health score to one writer agent. |
Responses: 200 Successful Response, 401 Unauthorized, 422 Validation Error