Skip to content

Data plane ​

The twelve core operations that AI agents call. Same endpoints whether you're on the bearer-token route (/v1/*) or the cookie-session mirror (/v1/me/*).

POST /v1/context ​

Low-friction first-pass grounding for the current user message. Intended as the first call before substantive agent work. It returns relevant hybrid search results, recent memories, and a structured contextPack grouped by memory type and scope (userGlobal vs projectScoped) in one response.

json
{
  "message": "user request or task summary",
  "namespace": "default",
  "includeNamespaces": ["..."],
  "k": 10,
  "project": "id or name",
  "includeProjects": ["..."],
  "maxSensitivity": "public|internal|private|sensitive"
}

Returns { relevant, recent } with the same result shape used by search/recent.

POST /v1/search ​

Hybrid retrieval across 5 signals (keyword + vector + graph + recency + entity). Default weights { keyword: 0.15, vector: 0.65, graph: 0.05, recency: 0.10, entity: 0.05 }; certain calibrations found graph and entity contribute nothing measurable and prefer them at 0.

json
{
  "query": "string (required)",
  "k": 10,
  "namespace": "single shelf to search",
  "includeNamespaces": ["restrict fanout to subset"],
  "project": "id or name",
  "includeProjects": ["active-project union"],
  "weights": {
    "keyword": 0.15,
    "vector": 0.65,
    "graph": 0.05,
    "recency": 0.1,
    "entity": 0.05
  },
  "agentName": "filter results to entries authored by this agent",
  "maxSensitivity": "public|internal|private|sensitive"
}

maxSensitivity defaults to private, which returns public, internal, and private entries while excluding sensitive entries unless explicitly requested.

Returns { results: SearchResult[], degraded: boolean }. Each result has id, score, content, tier, namespace, project, source, metadata, signals.

POST /v1/capture ​

Preferred agent-facing durable write after meaningful work. Same input shape as remember, but with semantic duplicate/update and contradiction supersession before insert.

json
{
  "content": "required, self-contained durable fact",
  "namespace": "default",
  "source": "agent name or origin",
  "sourceType": "doc|chat|email|code-review|inference|observation|system|manual",
  "capturedFrom": "conversation / run / channel ref",
  "confidence": 1.0,
  "agentName": "agent identifier",
  "project": "id or name",
  "metadata": {},
  "sensitivity": "public|internal|private|sensitive",
  "sourceRefs": ["sharepoint://sites/hr/policy.docx", "jira:HR-42"],
  "force": false
}

Responses:

  • { id } — inserted a fresh fact.
  • { id, deduplicated: true } — exact duplicate, existing entry reinforced.
  • { id, deduplicated: true, updated: true } — near-duplicate/refinement, existing active entry updated in place.
  • { id, superseded: ["01..."] } — new fact inserted and older contradictory active entries marked superseded.
  • { id: null, rejected: "<reason>" } — worthiness gate rejected the content.

Superseded entries are marked in metadata and hidden from normal search/context results; they are not hard-deleted.

sourceRefs (optional, at most 32 strings of 1-512 characters, no control characters) names the external sources the entry derives from. They are stored per entry, scoped to the caller's organization, and later let you remove everything derived from a source with POST /v1/forget {"sourceRef": ...}. If the write dedupes onto, or (capture) updates in place, an existing entry, the new refs are merged into it rather than replacing its refs, so forgetting any one of its sources removes the entry. A contradiction-supersede stores a new entry carrying the new refs and leaves the superseded entry with its own. Refs are not returned on read responses.

Captured entries are also annotated with typed metadata when possible:

  • memoryType: user_preference, setup_fact, project_convention, decision, bug_root_cause, deployment_state, safety_constraint, or general.
  • worthiness: v2 scoring object with durable, reuseLikelihood, userRelevance, confidence, and overall.
  • retention: memory-type policy such as long_lived, medium, current_only, plus baseEffectiveDays and supersedeAggressively.
  • sensitivity: privacy classification. Explicit sensitivity wins; otherwise NovaMem infers sensitive for obvious token/secret/password/API-key content and defaults to private.

POST /v1/session-recap ​

Batch ingest a curated end-of-session recap without dumping transcripts. The route accepts arrays such as decisions, setupFacts, rootCauses, preferences, projectConventions, safetyConstraints, and other, then stores each item through the same capture path with the appropriate memoryType.

Use this for durable outcomes after meaningful work: final deployment state, root causes, user preferences, and decisions. Do not pass raw chat logs or secrets.

POST /v1/hygiene ​

Read-only memory hygiene report for curation and debugging. The response includes a summary count block plus candidate lists for:

  • lowValue — low worthiness / too-short entries
  • stale — current-state facts worth review
  • duplicateClusters — high-overlap active memories
  • contradictionCandidates — comparable scalar conflicts not yet superseded
  • orphanCandidates — warm entries missing a cold/vector counterpart

POST /v1/evaluate ​

Run built-in memory quality checks. The response includes passed, summary, cases, and a compatibility checks alias. The core suite verifies that newer facts supersede older facts, context packs group typed memories, junk captures are rejected, hygiene reports are available, and retention policies are wired.

POST /v1/adoption ​

Read-only client adoption and refresh report. Use this when an MCP/agent client may be using stale tools or stale instructions after a server, shim, or skill update.

json
{
  "client": "hermes",
  "observedTools": ["memory_context", "memory_capture"],
  "observedInstructionsHash": "optional sha256"
}

Returns the current server-side MCP tool manifest, tool count, required adoption tools, MCP instructions hash, feature flags, client-specific refresh commands, and diagnostics. For Hermes, the refresh sequence is /reload-mcp, /reload-skills, then /reset or a fresh session.

POST /v1/remember ​

Raw write of a new entry. Worthiness gate + exact SHA dedup applied. For normal agent saves, prefer /v1/capture, which also handles semantic near-duplicates and contradiction supersession.

json
{
  "content": "required, 1-256KB",
  "namespace": "default",
  "source": "cli|web|...",
  "sourceType": "doc|chat|email|code-review|inference|observation|system|manual",
  "capturedFrom": "agent / channel ref",
  "confidence": 1.0,
  "agentName": "agent identifier",
  "project": "id or name",
  "metadata": {},
  "sensitivity": "public|internal|private|sensitive",
  "sourceRefs": ["sharepoint://sites/hr/policy.docx", "jira:HR-42"],
  "force": false
}

Response: { id } on success, { id: null, rejected: "<reason>" } on gate failure, { id, deduplicated: true } on exact duplicate.

sourceRefs (optional, at most 32 strings of 1-512 characters, no control characters) names the external sources the entry derives from. They are stored per entry, scoped to the caller's organization, and later let you remove everything derived from a source with POST /v1/forget {"sourceRef": ...}. If the write dedupes onto, or (capture) updates in place, an existing entry, the new refs are merged into it rather than replacing its refs, so forgetting any one of its sources removes the entry. A contradiction-supersede stores a new entry carrying the new refs and leaves the superseded entry with its own. Refs are not returned on read responses.

POST /v1/recent ​

Newest-first feed.

json
{
  "namespace": "default",
  "includeNamespaces": ["..."],
  "k": 20,
  "since": "ISO-8601 lower bound",
  "project": "...",
  "includeProjects": ["..."],
  "maxSensitivity": "public|internal|private|sensitive"
}

memory_today is recent with a 24 h since.

POST /v1/neighbors ​

Graph traversal from a seed entry id.

json
{
  "id": "ULID, required",
  "depth": 1,
  "k": 20,
  "project": "..."
}

depth is allowlisted to {1, 2, 3}. maxSensitivity defaults to private, which returns public, internal, and private entries while excluding sensitive entries unless explicitly requested.

Returns { results: SearchResult[], degraded: boolean }. Path-product aggregation along multi-hop walks.

POST /v1/forget ​

Hard delete, by id or by source reference. Give exactly one of id and sourceRef (400 otherwise).

json
{ "id": "ULID", "project": "scope check" }
{ "sourceRef": "sharepoint://sites/hr/policy.docx", "project": "optional" }

Cascades: warm row + FTS shadow + cold vector + graph node + edges + source refs.

By id returns { deleted, coldDeleteOk }. Idempotent — second call returns {deleted: false}.

By sourceRef removes every entry carrying that reference (see sourceRefs on remember/capture) and returns a receipt:

json
{
  "sourceRef": "...",
  "ids": ["01..", "01.."],
  "count": 2,
  "coldDeleteOk": true
}
  • Idempotent: a repeat, or a reference nothing carries, returns count: 0 and ids: [] with status 200.
  • Scope is the same as forget-by-id: without project only the caller's own user-wide entries are removed (inside the caller's organization; another user's, another organization's and project entries are never touched). With project, which must be one the caller is a member of, that project's entries carrying the ref are removed whatever member wrote them. A user's active project is applied by default, as for forget-by-id: with an active project and no project in the request, a forget by source covers only that project's entries, not the caller's user-wide ones, so pass an explicit project to choose a different project. On-behalf-of callers have no projects.
  • Matching is exact and case-sensitive, so two organizations can use the same reference string without interfering.
  • Ordering: all warm rows of every match go in one transaction, then the cold vectors. Retrieval resolves every hit through the warm rows, so once the transaction commits no match is retrievable even if the server dies before the cold cleanup; a vector whose delete fails is queued for the orphan reaper (coldDeleteOk: false). A crash can therefore never leave one match deleted and a sibling retrievable.

Over MCP, memory_forget takes sourceRef as an alternative to id and answers with the same receipt.

PUT /v1/memories/{id} ​

In-place rewrite. The id is supplied in the URL path. Preserves id, hits, edges, creation date. Re-embeds content if content is provided.

json
{
  "content": "new content (optional — omit to update only metadata)",
  "namespace": "...",
  "metadata": {},
  "sourceType": "...",
  "capturedFrom": "...",
  "confidence": 0.9
}

Returns { updated, embeddingChanged }.

GET /v1/stats ​

Per-caller statistics: byNamespace warm/cold counts, totals, last decay run.

Errors ​

Every route returns:

  • 400 — Zod validation failure with the path that failed
  • 401 — missing / invalid bearer
  • 403 — bearer scope mismatch (e.g. project-pinned token accessing another project)
  • 404 — entry / project not found
  • 429 — rate limit
  • 500 — engine error (logged, body has a generic message)

See also ​