Memory (AgentMemory)

How-toUpdated 63 min read
View as Markdown
On this page

Launch Film: Watch the @opvs-ai/agentmemory launch film at https://videos.spideriq.ai/videos/embed/564faf83-a8b8-4252-a070-aa4f0839a211?title=0&warningTitle=0&peertubeLink=0&p2p=0 or on the AgentMemory skill page.

Workspace Help: For dashboard instructions on reviewing, pinning, correcting, forgetting, and exporting an agent's memories at app.opvs.ai, see Review, pin and correct what an agent remembers. For raw OpenAPI endpoint schemas, see the AgentMemory HTTP API Reference.

Field

Value

Package

@opvs-ai/agentmemory v1.15.1 (schema 1.15.0)

Methods

47 (8 personal memory & recall · 9 typed code-graph lessons · 10 sources & sessions · 4 pipeline & maintenance · 6 curator verdicts · 7 shared craft & professions · 3 delivered/export/desk)

Base Path

https://api.opvs.ai/api/v1/memory

Authentication

Brand-scoped PAT (Authorization: Bearer $OPVS_PAT) or dashboard session cookie. Reads require memory:read; writes require memory:write. Cross-brand IDs return 404.

Default Format

yaml on context/recall endpoints (format=json for JSON, format=md for Markdown); json on CRUD and typed-entry routes.

Agent Context, Search & Personal Memory CRUD

searchMemories(agent_id, query, kinds?, limit?, format?)

Hybrid FTS search across the agent's memories — tsvector + GIN ranking returns memories matching the query, ordered by confidence and FTS relevance. Filter by kind for focused results.

  • HTTP Route: POST /api/v1/memory/agents/{agent_id}/context

  • Required Scope: memory:read

  • When to use: fast keyword/phrase recall — first thing to try when you remember a topic but not specifics

Parameter

In

Type

Required

Default

Description

agent_id

path

string

yes

—

The agent ID whose memories to search

query

query

string

yes

—

Natural language search query (matches title + body via tsvector)

kinds

query

array

no

—

Filter by memory kind — decision, learning, pattern, preference, fact, summary. Omit for all kinds.

limit

query

integer

no

10

Maximum results to return (max 50)

format

query

enum

no

yaml

Response format

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.searchMemories({ agent_id: "acme-sdr-001", query: "pricing page annual billing", kinds: "decision,learning" });
console.log(result);
// → 200 OK (POST /api/v1/memory/agents/{agent_id}/context)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

recallRelevant(agent_id, query, kinds?, limit?, format?)

Topic-aware recall using two-stage retrieval — FTS pre-filter (100 candidates) then an LLM reranker picks the most relevant. Better quality than raw searchMemories for fuzzy or conversational queries, but more expensive (one LLM call per recall).

  • HTTP Route: POST /api/v1/memory/agents/{agent_id}/context/relevant

  • Required Scope: memory:read

  • When to use: best-quality recall for fuzzy queries, conversation starters, or the start of a new task — when you need context, not just keyword hits

Parameter

In

Type

Required

Default

Description

agent_id

path

string

yes

—

The agent ID whose memories to search

query

query

string

yes

—

The topic, question, or conversation context to find relevant memories for. Full natural language works — the LLM reranker understands intent, not just keywords.

kinds

query

array

no

—

Filter by memory kind — decision, learning, pattern, preference, fact, summary

limit

query

integer

no

20

Maximum relevant memories to return (max 50)

format

query

enum

no

yaml

Response format

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.recallRelevant({ agent_id: "acme-sdr-001", query: "pricing page annual billing", kinds: "decision,learning" });
console.log(result);
// → 200 OK (POST /api/v1/memory/agents/{agent_id}/context/relevant)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

createMemory(agent_id, kind, title, body, tags?, confidence?, importance?, description?, source_session_ids?)

Persist a new memory deliberately. Use when you learn something that will be needed in a future session and isn't already in agentdocs or the agent's workspace files. Memories carry kind, title, body, confidence, importance, and optional tags.

  • HTTP Route: POST /api/v1/memory/memories

  • Required Scope: memory:write

  • When to use: explicit cross-session persistence — facts, decisions, learnings, preferences. ASK: 'will this be useful next week?' If not, skip the write.

Parameter

In

Type

Required

Default

Description

agent_id

body

string

yes

—

The agent ID to associate this memory with

kind

body

enum

yes

—

Memory kind — decision (choices made with rationale), learning (insight gained from experience), pattern (recurring observations — usually auto-consolidated from learnings), preference (stated user/team preferences), fact (objective info: URLs, IDs, version numbers).

title

body

string

yes

—

Concise title (≤100 chars). Searchable; surfaces first in result lists.

body

body

string

yes

—

Detailed description. No length cap, but compression kicks in for prose >50 tokens.

tags

body

array

no

—

Array of 1-5 tags for categorization. Tags enable auto-consolidation (3+ learnings with same tag → pattern).

confidence

body

number

no

0.8

Confidence score from 0.0 to 1.0. Decays ~2%/week unless `critical` importance or `summary` kind. Floor 0.1. Archived at <0.15 + age >30d.

importance

body

enum

no

normal

Importance level. `critical` is exempt from confidence decay. Critical = ops-blocking truth; high = often-needed; normal = default; low = rarely-needed.

description

body

string

no

—

One-line summary (≤200 chars) that recall shows beside the title.

source_session_ids

body

array

no

—

Ids of the sessions this memory came from (listSessions), when you know them.

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.createMemory({ agent_id: "acme-sdr-001", kind: "decision", title: "Quote annual prices first on the pricing page", body: "Prospects compared monthly prices against annual competitor tiers; lead with annual pricing." });
console.log(result);
// → 200 OK (POST /api/v1/memory/memories)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

getStats(format?, agent_id?)

Overview of the memory collection — total active count, breakdown by kind and importance, average confidence, and the count of archived memories. Lightweight introspection.

  • HTTP Route: GET /api/v1/memory/memories/stats

  • Required Scope: memory:read

  • When to use: verify the memory store has content, check distribution, debug 'why is no memory surfacing'

Parameter

In

Type

Required

Default

Description

format

query

enum

no

yaml

Response format

agent_id

query

string

no

—

Count only this agent's memories; the whole brand when omitted

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.getStats({ format: "json", agent_id: "acme-sdr-001" });
console.log(result);
// → 200 OK (GET /api/v1/memory/memories/stats)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

updateMemory(memory_id, title?, body?, description?, kind?, tags?, confidence?, importance?, status?)

Correct an existing memory in place. Use when a stored fact changed, a title was wrong, or a memory's confidence/importance should be re-rated. Only the fields you send are touched.

  • HTTP Route: PATCH /api/v1/memory/memories/{memory_id}

  • Required Scope: memory:write

  • When to use: fix a memory you already wrote — a fact that moved, a mis-picked `kind`, a confidence that is now too high. Correcting beats writing a second, contradicting memory

Parameter

In

Type

Required

Default

Description

memory_id

path

string

yes

—

The memory's UUID (from searchMemories / createMemory).

title

body

string

no

—

Replacement title (≤100 chars).

body

body

string

no

—

Replacement body.

description

body

string

no

—

Replacement one-line summary (≤200 chars). Recall returns it beside the title, so when a correction changes what the body says, correct this too, or recall keeps showing the old summary.

kind

body

enum

no

—

Re-classify the memory.

tags

body

array

no

—

Replacement tag list (replaces, does not merge).

confidence

body

number

no

—

Re-rate confidence, 0.0–1.0.

importance

body

enum

no

—

Re-rate importance. `critical` is exempt from decay.

status

body

enum

no

—

`archived` retires a memory from recall without deleting it — the right move for something superseded rather than wrong.

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.updateMemory({ memory_id: "5eb50fe5-111c-45d2-a3a0-29ef3485dbe4", title: "Quote annual prices first on the pricing page", body: "Prospects compared monthly prices against annual competitor tiers; lead with annual pricing." });
console.log(result);
// → 200 OK (PATCH /api/v1/memory/memories/{memory_id})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

deleteMemory(memory_id)

Soft-delete a memory. Use for something written by mistake, a duplicate from a re-run seeding script, or a test row. The row is marked deleted, not destroyed.

  • HTTP Route: DELETE /api/v1/memory/memories/{memory_id}

  • Required Scope: memory:write

  • When to use: remove a memory that should never have been written — a duplicate, a test row, a fact that was wrong rather than merely stale

Parameter

In

Type

Required

Default

Description

memory_id

path

string

yes

—

The memory's UUID (from searchMemories / createMemory).

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.deleteMemory({ memory_id: "5eb50fe5-111c-45d2-a3a0-29ef3485dbe4" });
console.log(result);
// → 200 OK (DELETE /api/v1/memory/memories/{memory_id})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

listMemories(format?, query?, agent_id?, kinds?, tags?, min_confidence?, importance?, status?, forgotten?, limit?, offset?)

Page through the brand's stored memories with exact filters (agent, kind, tag, importance, status). `query` adds a full-text match. `origin_brand_id` is runtime-only: the gateway sets it from your token.

  • HTTP Route: GET /api/v1/memory/memories

  • Required Scope: memory:read

  • When to use: browse or audit stored memories page by page, e.g. one agent's `fact` memories or the archived ones; for topic recall use recallRelevant

Parameter

In

Type

Required

Default

Description

format

query

enum

no

—

Reply rendering; json when omitted

query

query

string

no

—

Full-text match on title and body

agent_id

query

string

no

—

Only this agent's memories

kinds

query

string

no

—

Comma-separated kinds, e.g. "fact,decision"

tags

query

string

no

—

Comma-separated tags; a memory matches when it has any of them

min_confidence

query

number

no

—

Only memories at or above this confidence, 0.0-1.0

importance

query

enum

no

—

Only memories of this importance

status

query

string

no

active

Memory status to list; `active` by default, `archived` for retired ones

forgotten

query

boolean

no

False

true lists the memories people marked forgotten instead of the rest

limit

query

integer

no

20

Page size

offset

query

integer

no

0

Rows to skip; add `limit` for the next page

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listMemories({ format: "json", query: "pricing page annual billing", agent_id: "acme-sdr-001" });
console.log(result);
// → 200 OK (GET /api/v1/memory/memories)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

getMemory(format?, memory_id)

Read one memory in full by id, including its confidence, access count and pin state.

  • HTTP Route: GET /api/v1/memory/memories/{memory_id}

  • Required Scope: memory:read

  • When to use: read one memory by id, e.g. before updateMemory, or to check a recalled memory's confidence and tags

Parameter

In

Type

Required

Default

Description

format

query

enum

no

—

Reply rendering; json when omitted

memory_id

path

string

yes

—

The memory's UUID (from listMemories, searchMemories or createMemory)

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.getMemory({ memory_id: "5eb50fe5-111c-45d2-a3a0-29ef3485dbe4", format: "json" });
console.log(result);
// → 200 OK (GET /api/v1/memory/memories/{memory_id})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

Typed Code-Graph Lessons & Anchors

searchEntries(q?, scope?, type?, anchor?, project_id?, card?, derived_from?, author?, stale?, unguarded?, pinned_first?, include_retired?, limit?)

Search typed memory entries with full-text ranking and optional scope, type, file-anchor, card, guard, origin, pinned-first, and retired-entry filters. Results carry `unguarded`, `derived_from`, and `anchor_states[].role`; `matched_by` may be `guard`.

  • HTTP Route: GET /api/v1/memory/entries/search

  • Required Scope: memory:read

  • When to use: search durable typed entries when you need decisions, learnings, or other repository memory beyond an agent's personal memories

Parameter

In

Type

Required

Default

Description

q

query

string

no

—

Search text; empty browses up to 500 matching entries, pinned then newest

scope

query

string

no

—

Exact entry scope to include

type

query

string

no

—

Exact typed-entry kind to include

anchor

query

string

no

—

File path or other anchor attached to the entry

project_id

query

uuid

no

—

Narrow anchor matches to one code project; without it, every project of your brand counts

card

query

string

no

—

Exact card reference linked to the entry

derived_from

query

string

no

—

Exact incident/card reference or URL linked to the entry

author

query

string

no

—

Exact entry author to include

stale

query

boolean

no

—

Filter by code-anchor staleness

unguarded

query

boolean

no

—

Filter by whether every declared guard is missing or removed

pinned_first

query

boolean

no

True

Rank pinned entries before unpinned entries

include_retired

query

boolean

no

False

Include retired entries in the results

limit

query

integer

no

20

Maximum matching entries to return

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.searchEntries({ q: "pat scope check", scope: "sample-scope", type: "sample-type" });
console.log(result);
// → 200 OK (GET /api/v1/memory/entries/search)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

getEntry(entry_id)

Fetch one complete typed memory entry by its path-like ID.

  • HTTP Route: GET /api/v1/memory/entries/{entry_id}

  • Required Scope: memory:read

  • When to use: read the complete entry after searchEntries or entryContext returns its ID

Parameter

In

Type

Required

Default

Description

entry_id

path

string

yes

—

Path-like entry ID; `/` characters are allowed

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.getEntry({ entry_id: "api/auth/pat-scope-check" });
console.log(result);
// → 200 OK (GET /api/v1/memory/entries/{entry_id})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

entryContext(anchor, project_id?, author?, stale?, unguarded?, derived_from?, pinned_first?, limit?)

Find lessons for the file you are about to edit, with pinned entries ranked first. Also returns lessons on the file's functions and on its folders; each result carries `unguarded`, `derived_from`, `anchor_states[].role`, and says how it matched (`matched_by`: anchor, symbol, folder, or guard). A narrow view: for every filter use searchEntries.

  • HTTP Route: GET /api/v1/memory/entries/search

  • Required Scope: memory:read

  • When to use: lessons for the file you are about to edit; pass exactly one repository-relative file path as `anchor`

Parameter

In

Type

Required

Default

Description

anchor

query

string

yes

—

One repository-relative file path you are about to edit

project_id

query

uuid

no

—

Narrow anchor matches to one code project; without it, every project of your brand counts

author

query

string

no

—

Exact entry author to include

stale

query

boolean

no

—

Filter by code-anchor staleness

unguarded

query

boolean

no

—

Filter by whether every declared guard is missing or removed

derived_from

query

string

no

—

Exact incident/card reference or URL linked to the entry

pinned_first

query

boolean

no

True

Rank pinned lessons before unpinned lessons

limit

query

integer

no

20

Maximum matching entries to return

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.entryContext({ anchor: "services/auth/pat.py", project_id: "1851acb6-8eb0-4be9-abd5-13cc48ff7134", author: "sample-author" });
console.log(result);
// → 200 OK (GET /api/v1/memory/entries/search)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

entriesNear(project_id, node_ids?, paths?, depth?, kinds?, direction?, hub_cap?, limit?)

Walk the code graph up to N hops from the caller's chosen files or code-node ids and return the live lessons on every node the walk reaches. The order is pinned first, then hops, then guard-in-walk last, then id. Each entry may carry `guard: {anchors, paths, node_ids, in_walk, unguarded}` or null. `anchors` are the paths the lesson declared; `paths` are where those guards are now, and are the paths to open. On an older server `paths` may be absent, so resolve `node_ids` instead. `in_walk` means the guard's node, or any node of the guard's file, is in the reached set. `truncated: true` means lessons were left out, either by `limit` or because a reached node holds more lessons than came back; raise `limit` or narrow the seeds. `guard_lookup_truncated: true` means there were more than 5,000 guard ids, so `in_walk` may be wrong for some lessons. Hub files are damped (capped at `hub_cap`) so a single popular module cannot dominate the answer.

  • HTTP Route: POST /api/v1/memory/entries:near

  • Required Scope: memory:read

  • When to use: before changing files or functions: the lessons on that code and on the code within 1–2 hops

Parameter

In

Type

Required

Default

Description

project_id

body

uuid

yes

—

Project whose code graph is being walked

node_ids

body

array

no

[]

Code-node ids to seed the walk (≤50). Use node ids when you already hold them (for example from the code-index skill); otherwise pass `paths`, which the gateway resolves. Combine with `paths` for up to 50 seeds total.

paths

body

array

no

[]

Repository-relative file paths to seed the walk (≤50). The gateway resolves each one to a code node before walking. Combine with `node_ids` for up to 50 seeds total.

depth

body

integer

no

2

Maximum hops from a seed node (0 = lessons on seeds only)

kinds

body

array

no

['import', 'contains']

Code-graph edge kinds the walk is allowed to traverse

direction

body

enum

no

both

Whether to walk incoming edges, outgoing edges, or both

hub_cap

body

integer

no

25

Maximum number of distinct seed neighbors before a node is damped (returned in `damped` but not expanded further).

limit

body

integer

no

20

Maximum lessons to return across the whole walk

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.entriesNear({ project_id: "1851acb6-8eb0-4be9-abd5-13cc48ff7134", node_ids: ["sym:validate_brand_scope"], paths: ["services/auth/pat.py"] });
console.log(result);
// → 200 OK (POST /api/v1/memory/entries:near)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

entriesSimilar(text, type?, k?, threshold?)

Compare a free-text lesson draft against the brand's live typed entries by embedding similarity. Returns the top-k matches above a configurable threshold so the caller can decide whether to write a new entry or update an existing one.

  • HTTP Route: POST /api/v1/memory/entries:similar

  • Required Scope: memory:read

  • When to use: before writing a lesson, check whether one already exists

Parameter

In

Type

Required

Default

Description

text

body

string

yes

—

The lesson draft to compare against live entries

type

body

string

no

—

Narrow candidates to one typed-entry kind before comparing

k

body

integer

no

3

Maximum matches to return

threshold

body

number

no

—

Cosine similarity threshold (default = server's `entry_duplicate_similarity_threshold`). Anything at or above this is a near-duplicate; below it is treated as a new lesson.

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.entriesSimilar({ text: "Always validate X-Brand-ID against token brand membership before querying tenant rows.", type: "sample-type", k: 3 });
console.log(result);
// → 200 OK (POST /api/v1/memory/entries:similar)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

listStaleEntries(author, stale?, pinned_first?, limit?)

List the lessons the caller has authored whose anchors became stale (the code they were about was removed, not merely moved). Ordered oldest first so the caller can triage from the longest-pending ones. A narrow view: for every filter use searchEntries.

  • HTTP Route: GET /api/v1/memory/entries/search

  • Required Scope: memory:read

  • When to use: weekly or per-card check — keep your authored lessons accurate when their underlying code is deleted

Parameter

In

Type

Required

Default

Description

author

query

string

yes

—

Exact entry author to include — pass the caller's own agent id

stale

query

boolean

no

True

Filter by code-anchor staleness. Default `true`: only entries whose code was removed.

pinned_first

query

boolean

no

False

Listed in created-at order (oldest first), not pinned-first. Default `false` because the rows the caller needs to triage are the oldest unpinned ones.

limit

query

integer

no

20

Maximum matching entries to return

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listStaleEntries({ author: "sample-author", stale: true, pinned_first: false });
console.log(result);
// → 200 OK (GET /api/v1/memory/entries/search)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

anchorsLookup(project_id, node_ids, per_node_limit?)

Find lessons for the code nodes you already hold, with pinned entries ranked first. Each node returns at most `per_node_limit` lessons; `counts` holds the real number, so compare the returned entry count with it. Each entry carries `guard_anchors`, the paths the lesson declared, and `guard_paths`, where those guards are now.

  • HTTP Route: POST /api/v1/memory/anchors:lookup

  • Required Scope: memory:read

  • When to use: lessons attached to code nodes you already hold (from the code-index skill's resolve or graph), pinned first

Parameter

In

Type

Required

Default

Description

project_id

body

uuid

yes

—

Project whose code nodes are being looked up

node_ids

body

array

yes

—

Code-node ids returned by the code-index skill (≤1000). The gateway resolves them — pass node ids, never file paths.

per_node_limit

body

integer

no

5

Maximum lessons to return for each requested node

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.anchorsLookup({ project_id: "1851acb6-8eb0-4be9-abd5-13cc48ff7134", node_ids: ["sym:validate_brand_scope"], per_node_limit: 5 });
console.log(result);
// → 200 OK (POST /api/v1/memory/anchors:lookup)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

getEntryStats()

Exact counts of the brand's typed lessons: total, pinned, stale, retracted and not yet reviewed.

  • HTTP Route: GET /api/v1/memory/entries/stats

  • Required Scope: memory:read

  • When to use: count the brand's lessons before a triage, e.g. how many are stale or unreviewed

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.getEntryStats({});
console.log(result);
// → 200 OK (GET /api/v1/memory/entries/stats)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

syncKnowledge(repo, branch, commit, project_id, files, truncated?)

Pin one commit's repository knowledge files to a code project you own; lessons declared in them are added, updated or retracted. `resolved_anchors` is runtime-only: the gateway computes it from your brand.

  • HTTP Route: POST /api/v1/memory/knowledge:sync

  • Required Scope: memory:write

  • When to use: sync a repository's knowledge files at one commit; `opvs memory sync` reads them from disk and builds this body, so prefer running it

Parameter

In

Type

Required

Default

Description

repo

body

string

yes

—

Repository name, e.g. "owner/name"

branch

body

string

yes

—

Branch the commit is on

commit

body

string

yes

—

Full 40-character commit sha

project_id

body

string

yes

—

UUID of your brand's code project

files

body

array

yes

—

The knowledge files at that commit

truncated

body

object

no

—

Set when you sent only part of the files

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.syncKnowledge({ repo: "sample-repo", branch: "sample-branch", commit: "sample-commit", project_id: "1851acb6-8eb0-4be9-abd5-13cc48ff7134", files: ["services/auth/pat.py"] });
console.log(result);
// → 200 OK (POST /api/v1/memory/knowledge:sync)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

Extraction Sources, Sessions & Ingestion

listSources(format?, agent_id?)

List the extraction sources that feed memory (openclaw, agentboard, claude_code, capture) and when each last synced.

  • HTTP Route: GET /api/v1/memory/sources

  • Required Scope: memory:read

  • When to use: see which sources feed an agent's memory and when each last synced

Parameter

In

Type

Required

Default

Description

format

query

enum

no

—

Reply rendering; json when omitted

agent_id

query

string

no

—

Only this agent's sources

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listSources({ format: "json", agent_id: "acme-sdr-001" });
console.log(result);
// → 200 OK (GET /api/v1/memory/sources)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

getSource(source_id)

Read one extraction source by id.

  • HTTP Route: GET /api/v1/memory/sources/{source_id}

  • Required Scope: memory:read

  • When to use: check one source's type, config, enabled flag and last sync time

Parameter

In

Type

Required

Default

Description

source_id

path

string

yes

—

The source's UUID (from listSources)

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.getSource({ source_id: "be3b0d9a-4f12-4a8e-9b11-0f12a34c5678" });
console.log(result);
// → 200 OK (GET /api/v1/memory/sources/{source_id})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

createSource(agent_id, source_type, config?, enabled?)

Register a new extraction source for one of your brand's own agents. The scheduler then discovers and extracts its sessions.

  • HTTP Route: POST /api/v1/memory/sources

  • Required Scope: memory:write

  • When to use: register a source only when asked, and only after listSources shows none of this type for the agent

Parameter

In

Type

Required

Default

Description

agent_id

body

string

yes

—

Agent workspace id the source belongs to

source_type

body

enum

yes

—

Where the sessions come from

config

body

object

no

—

Source-specific settings; omit for the defaults

enabled

body

boolean

no

True

false registers the source paused

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.createSource({ agent_id: "acme-sdr-001", source_type: "openclaw", config: {"source": "conversation"} });
console.log(result);
// → 200 OK (POST /api/v1/memory/sources)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

updateSource(source_id, config?, enabled?)

Pause, resume or reconfigure an extraction source. Only the fields you send change.

  • HTTP Route: PATCH /api/v1/memory/sources/{source_id}

  • Required Scope: memory:write

  • When to use: pause (`enabled: false`) or resume a source, or change its config

Parameter

In

Type

Required

Default

Description

source_id

path

string

yes

—

The source's UUID (from listSources)

config

body

object

no

—

Replacement source-specific settings

enabled

body

boolean

no

—

false pauses the source, true resumes it

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.updateSource({ source_id: "be3b0d9a-4f12-4a8e-9b11-0f12a34c5678", config: {"source": "conversation"}, enabled: true });
console.log(result);
// → 200 OK (PATCH /api/v1/memory/sources/{source_id})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

deleteSource(source_id)

Soft-delete an extraction source so it no longer feeds memory.

  • HTTP Route: DELETE /api/v1/memory/sources/{source_id}

  • Required Scope: memory:write

  • When to use: remove a source that should never feed memory again; to stop it for a while, updateSource(enabled=false) instead

Parameter

In

Type

Required

Default

Description

source_id

path

string

yes

—

The source's UUID (from listSources)

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.deleteSource({ source_id: "be3b0d9a-4f12-4a8e-9b11-0f12a34c5678" });
console.log(result);
// → 200 OK (DELETE /api/v1/memory/sources/{source_id})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

syncSource(source_id)

Discover new sessions for one source now, instead of waiting for the 10-minute scheduled sync.

  • HTTP Route: POST /api/v1/memory/sources/{source_id}/sync

  • Required Scope: memory:write

  • When to use: pick up a just-finished conversation now instead of waiting for the 10-minute sync

Parameter

In

Type

Required

Default

Description

source_id

path

string

yes

—

The source's UUID (from listSources); a disabled source returns 400

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.syncSource({ source_id: "be3b0d9a-4f12-4a8e-9b11-0f12a34c5678" });
console.log(result);
// → 200 OK (POST /api/v1/memory/sources/{source_id}/sync)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

listSessions(format?, agent_id?, source_id?, status?, page?, page_size?)

List the conversations catalogued for memory extraction and their status (pending, extracted, failed, refused).

  • HTTP Route: GET /api/v1/memory/sessions

  • Required Scope: memory:read

  • When to use: see which conversations were catalogued and whether each was extracted

Parameter

In

Type

Required

Default

Description

format

query

enum

no

—

Reply rendering; json when omitted

agent_id

query

string

no

—

Only this agent's sessions

source_id

query

string

no

—

Only sessions from this source

status

query

string

no

—

Only sessions in this status, e.g. pending, extracted, failed, refused

page

query

integer

no

1

Page number, from 1

page_size

query

integer

no

50

Rows per page

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listSessions({ format: "json", agent_id: "acme-sdr-001", source_id: "be3b0d9a-4f12-4a8e-9b11-0f12a34c5678" });
console.log(result);
// → 200 OK (GET /api/v1/memory/sessions)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

getSession(session_id)

Read one catalogued session by id.

  • HTTP Route: GET /api/v1/memory/sessions/{session_id}

  • Required Scope: memory:read

  • When to use: check one session's status, message count and time span

Parameter

In

Type

Required

Default

Description

session_id

path

string

yes

—

The session's UUID (from listSessions)

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.getSession({ session_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7" });
console.log(result);
// → 200 OK (GET /api/v1/memory/sessions/{session_id})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

ingestSessionEvents(runtime, session_id, events)

Upload one batch of already-redacted session events from a local coding runtime; it is stored as a pending session for extraction.

  • HTTP Route: POST /api/v1/memory/ingest

  • Required Scope: memory:write

  • When to use: upload a local session's events for memory extraction; `opvs memory capture` builds and redacts this body for you, so prefer running it

Parameter

In

Type

Required

Default

Description

runtime

body

enum

yes

—

The runtime the session ran in

session_id

body

string

yes

—

The runtime's own session id; a re-upload with the same id adds only new events

events

body

array

yes

—

1-500 events in order

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.ingestSessionEvents({ runtime: "sample-runtime", session_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7", events: [{"role": "user", "content": "Always run migrations in a transaction."}] });
console.log(result);
// → 200 OK (POST /api/v1/memory/ingest)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

extractAgentSessions(agent_id)

Sync one agent's enabled sources and queue its pending sessions for extraction, in the background. The dashboard does this when a chat ends.

  • HTTP Route: POST /api/v1/memory/agents/{agent_id}/extract-on-disconnect

  • Required Scope: memory:write

  • When to use: after a conversation you want remembered soon, queue its agent's sessions instead of waiting for the 10-minute sync

Parameter

In

Type

Required

Default

Description

agent_id

path

string

yes

—

Agent workspace id whose sessions to extract

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.extractAgentSessions({ agent_id: "acme-sdr-001" });
console.log(result);
// → 200 OK (POST /api/v1/memory/agents/{agent_id}/extract-on-disconnect)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

Pipeline & Maintenance Runs

listExtractionRuns(format?, source_id?, agent_id?, page?, page_size?)

Extraction run history: sessions processed, memories created or updated, and the error of a failed run.

  • HTTP Route: GET /api/v1/memory/pipeline/runs

  • Required Scope: memory:read

  • When to use: check whether extraction ran and what it produced, e.g. why a conversation left no memory

Parameter

In

Type

Required

Default

Description

format

query

enum

no

—

Reply rendering; json when omitted

source_id

query

string

no

—

Only runs for this source

agent_id

query

string

no

—

Only runs for this agent

page

query

integer

no

1

Page number, from 1

page_size

query

integer

no

20

Rows per page

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listExtractionRuns({ format: "json", source_id: "be3b0d9a-4f12-4a8e-9b11-0f12a34c5678", agent_id: "acme-sdr-001" });
console.log(result);
// → 200 OK (GET /api/v1/memory/pipeline/runs)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

listMaintenanceRuns(format?, operation?, page?, page_size?)

Maintenance run history: when confidence decay, dedup, archive and consolidation last ran and how many memories each touched.

  • HTTP Route: GET /api/v1/memory/pipeline/maintenance-runs

  • Required Scope: memory:read

  • When to use: find out why a memory left recall: it may have been archived, merged or decayed here

Parameter

In

Type

Required

Default

Description

format

query

enum

no

—

Reply rendering; json when omitted

operation

query

string

no

—

Only this operation, e.g. confidence_decay, dedup_merge, archive, consolidate

page

query

integer

no

1

Page number, from 1

page_size

query

integer

no

20

Rows per page

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listMaintenanceRuns({ format: "json", operation: "sample-operation", page: 1 });
console.log(result);
// → 200 OK (GET /api/v1/memory/pipeline/maintenance-runs)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

triggerExtraction(source_id)

Queue extraction now for every pending session of one source. Counts against the brand's daily extraction quota.

  • HTTP Route: POST /api/v1/memory/pipeline/extract/{source_id}

  • Required Scope: memory:write

  • When to use: extract a source's pending sessions now, when asked; the scheduler otherwise does it every 10 minutes

Parameter

In

Type

Required

Default

Description

source_id

path

string

yes

—

The source's UUID (from listSources)

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.triggerExtraction({ source_id: "be3b0d9a-4f12-4a8e-9b11-0f12a34c5678" });
console.log(result);
// → 200 OK (POST /api/v1/memory/pipeline/extract/{source_id})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

runMaintenance(operation?)

Run memory maintenance now for the whole brand: confidence decay, dedup merge, archive and consolidation, or one of them.

  • HTTP Route: POST /api/v1/memory/pipeline/maintain

  • Required Scope: memory:write

  • When to use: run maintenance only when asked, e.g. after a bulk cleanup; it also runs every 6 hours on its own

Parameter

In

Type

Required

Default

Description

operation

query

enum

no

—

One operation; omit to run all four

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.runMaintenance({ operation: "sample-operation" });
console.log(result);
// → 200 OK (POST /api/v1/memory/pipeline/maintain)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

Memory Curator & Shadow Verdicts

listPendingEntries(since, limit?)

List new unreviewed typed-memory entries created on or after `since`, plus every stale entry regardless of its creation time, for shadow review.

  • HTTP Route: GET /api/v1/memory/entries/pending

  • Required Scope: memory:read

  • When to use: fetch the review set ONCE per run; a daily run passes `since` as the start of its previous run, or now minus 24 hours on a first run

Parameter

In

Type

Required

Default

Description

since

query

string

yes

—

ISO-8601 date-time; include entries created on or after this time, plus every stale entry regardless

limit

query

integer

no

50

Maximum entries to return

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listPendingEntries({ since: "2026-11-01T00:00:00Z", limit: 10 });
console.log(result);
// → 200 OK (GET /api/v1/memory/entries/pending)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

submitEntryVerdict(entry_id, verdict, reason, evidence?, reviewer)

Store one reasoned Memory Curator verdict for a typed-memory entry in shadow, without applying any proposed action.

  • HTTP Route: POST /api/v1/memory/entries/{entry_id}/verdicts

  • Required Scope: memory:write

  • When to use: submit one reasoned verdict per entry per run after reviewing the pending set

Parameter

In

Type

Required

Default

Description

entry_id

path

string

yes

—

Path-like entry ID, such as memory/2026-10-01-x.md

verdict

body

enum

yes

—

Shadow verdict or human-action proposal

reason

body

string

yes

—

Reason for the verdict

evidence

body

object

no

—

Structured evidence supporting the verdict

reviewer

body

string

yes

—

Memory Curator agent ID

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.submitEntryVerdict({ entry_id: "api/auth/pat-scope-check", verdict: "keep", reason: "Verified against current production billing flow and recent customer conversations.", reviewer: "sample-reviewer" });
console.log(result);
// → 200 OK (POST /api/v1/memory/entries/{entry_id}/verdicts)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

listEntryVerdicts(since, limit?, cursor?, reviewer?)

Curator verdicts on typed lessons since a date, oldest first, with any human override.

  • HTTP Route: GET /api/v1/memory/entries/verdicts

  • Required Scope: memory:read

  • When to use: read the curator verdicts given since a date; pass `cursor` from the last reply for the next page

Parameter

In

Type

Required

Default

Description

since

query

string

yes

—

ISO-8601 date-time; verdicts created at or after it

limit

query

integer

no

200

Page size

cursor

query

string

no

—

The `cursor` of the previous reply, for the next page

reviewer

query

string

no

—

Only verdicts by this reviewer agent id

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listEntryVerdicts({ since: "2026-11-01T00:00:00Z", limit: 10, cursor: "sample-cursor" });
console.log(result);
// → 200 OK (GET /api/v1/memory/entries/verdicts)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

listMemoriesForReview(since, limit?)

List the brand's agent memories pending shadow review. Only the brand's hired Memory Curator may call this method; the gateway pins the brand. `origin_brand_id` is runtime-only: the gateway sets it from your token.

  • HTTP Route: GET /api/v1/memory/my/memories/review/pending

  • Required Scope: memory:read

  • When to use: fetch ONCE per run with `since` set to 24 hours before now and `limit` 50

Parameter

In

Type

Required

Default

Description

since

query

string

yes

—

ISO-8601 datetime set to 24 hours before the start of this run

limit

query

integer

no

50

Maximum memories to return

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listMemoriesForReview({ since: "2026-11-01T00:00:00Z", limit: 10 });
console.log(result);
// → 200 OK (GET /api/v1/memory/my/memories/review/pending)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

submitMemoryVerdict(memory_id, verdict, reason, evidence?)

Record one reasoned shadow verdict for a brand agent memory without applying any memory change. Only the brand's hired Memory Curator may call this method; the gateway sets the reviewer itself. `reviewer` and `origin_brand_id` are runtime-only: the gateway sets them.

  • HTTP Route: POST /api/v1/memory/my/memories/{memory_id}/verdicts

  • Required Scope: memory:write

  • When to use: submit one evidence-first verdict per memory per run with one short reason; for `correct-proposed`, put corrected text in `evidence.suggested_body`

Parameter

In

Type

Required

Default

Description

memory_id

path

string

yes

—

Memory UUID returned by listMemoriesForReview

verdict

body

enum

yes

—

Shadow verdict or proposed memory change

reason

body

string

yes

—

One short reason grounded in the supplied evidence; max 2000 characters

evidence

body

object

no

—

Supporting evidence; include suggested_body with the corrected text for correct-proposed, never secret values

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.submitMemoryVerdict({ memory_id: "5eb50fe5-111c-45d2-a3a0-29ef3485dbe4", verdict: "keep", reason: "Verified against current production billing flow and recent customer conversations." });
console.log(result);
// → 200 OK (POST /api/v1/memory/my/memories/{memory_id}/verdicts)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

listMemoryVerdicts(since, limit?, cursor?)

The brand's past shadow verdicts on agent memories since a date, for the brand's hired Memory Curator.

  • HTTP Route: GET /api/v1/memory/my/memories/verdicts

  • Required Scope: memory:read

  • When to use: Memory Curator only: read the verdicts already given since a date, so you do not judge the same memory twice

Parameter

In

Type

Required

Default

Description

since

query

string

yes

—

ISO-8601 date-time; verdicts created at or after it

limit

query

integer

no

200

Page size

cursor

query

string

no

—

The `cursor` of the previous reply, for the next page

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listMemoryVerdicts({ since: "2026-11-01T00:00:00Z", limit: 10, cursor: "sample-cursor" });
console.log(result);
// → 200 OK (GET /api/v1/memory/my/memories/verdicts)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

Shared Craft, Skill Lessons & Profession Workflows

contributeSkillLesson(vendor, name, kind, body, tags?, source_engagement_hash, craft_id?)

Contribute a reusable learning or pattern to an installed skill's shared craft queue for review before publication.

  • HTTP Route: POST /api/v1/memory/skill-lessons/{vendor}/{name}

  • Required Scope: memory:write

  • When to use: share a lesson that is specific to an installed skill and reusable by agents outside the current engagement

Parameter

In

Type

Required

Default

Description

vendor

path

string

yes

—

Skill vendor slug, with or without one leading @

name

path

string

yes

—

Skill package name

kind

body

enum

yes

—

Whether this contribution is a learned fact or a recurring pattern

body

body

string

yes

—

Reusable lesson text for the shared craft queue

tags

body

array

no

—

Search and grouping tags for the lesson

source_engagement_hash

body

string

yes

—

One-way hash of the engagement, computed by the caller; never a brand, tenant or client id

craft_id

body

string

no

—

Stable idempotency key for retrying the same contribution

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.contributeSkillLesson({ vendor: "opvs-ai", name: "agentmemory", kind: "decision", body: "Prospects compared monthly prices against annual competitor tiers; lead with annual pricing.", source_engagement_hash: "sample-source_engagement_hash" });
console.log(result);
// → 200 OK (POST /api/v1/memory/skill-lessons/{vendor}/{name})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

pullSkillLessons(vendor, name, since?, query?, limit?)

Pull published shared lessons for a skill actively installed by the caller's pinned brand. `version_pin` is runtime-only: the gateway does not forward it.

  • HTTP Route: GET /api/v1/memory/skill-lessons/{vendor}/{name}

  • Required Scope: memory:read

  • When to use: load reusable learnings and patterns for an installed skill before starting work that uses it

Parameter

In

Type

Required

Default

Description

vendor

path

string

yes

—

Skill vendor slug, with or without one leading @

name

path

string

yes

—

Skill package name

since

query

string

no

—

Opaque cursor value from a previous pullSkillLessons reply; omit for the first page

query

query

string

no

—

Search text for narrowing the published lessons

limit

query

integer

no

—

Maximum lessons to return; at most 200

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.pullSkillLessons({ vendor: "opvs-ai", name: "agentmemory", since: "2026-11-01T00:00:00Z" });
console.log(result);
// → 200 OK (GET /api/v1/memory/skill-lessons/{vendor}/{name})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

listCraftPendingCodes()

List profession codes that currently have at least one pending shared craft row for the platform Memory Curator.

  • HTTP Route: GET /api/v1/memory/professions/review/pending-codes

  • Required Scope: memory:read

  • When to use: discover which shared craft queues need curator review before fetching any one profession's queue

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listCraftPendingCodes({});
console.log(result);
// → 200 OK (GET /api/v1/memory/professions/review/pending-codes)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

curatorCraftQueue(profession_code, limit?)

Read one profession's pending shared-craft review queue, including the newest shadow curator verdict attached to each craft row. `unjudged` is runtime-only: the gateway always sends true.

  • HTTP Route: GET /api/v1/memory/professions/{profession_code}/craft/curator-queue

  • Required Scope: memory:read

  • When to use: review pending craft for one profession code returned by listCraftPendingCodes

Parameter

In

Type

Required

Default

Description

profession_code

path

string

yes

—

Profession code whose pending craft should be reviewed

limit

query

integer

no

—

Maximum pending craft rows to return

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.curatorCraftQueue({ profession_code: "threads-content-creator", limit: 10 });
console.log(result);
// → 200 OK (GET /api/v1/memory/professions/{profession_code}/craft/curator-queue)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

postCraftVerdict(profession_code, craft_id, verdict, reason, evidence?)

Record a reasoned publish-or-reject recommendation for one pending shared-craft row without applying it. `reviewer` is runtime-only: the gateway sets it to the calling agent.

  • HTTP Route: POST /api/v1/memory/professions/{profession_code}/craft/{craft_id}/verdicts

  • Required Scope: memory:write

  • When to use: submit the Memory Curator's shadow verdict after reviewing one pending craft row and its evidence

Parameter

In

Type

Required

Default

Description

profession_code

path

string

yes

—

Profession code that owns the craft row

craft_id

path

string

yes

—

Pending craft row identifier

verdict

body

enum

yes

—

Shadow recommendation for the human reviewer

reason

body

string

yes

—

Reasoned explanation for the verdict

evidence

body

object

no

—

Structured evidence supporting the recommendation

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.postCraftVerdict({ profession_code: "threads-content-creator", craft_id: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", verdict: "keep", reason: "Verified against current production billing flow and recent customer conversations." });
console.log(result);
// → 200 OK (POST /api/v1/memory/professions/{profession_code}/craft/{craft_id}/verdicts)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:write or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:write and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

getProfession(profession_code)

Look up a profession's guild-hall address profile by its code, e.g. before hiring it. Not limited to members.

  • HTTP Route: GET /api/v1/memory/professions/{profession_code}

  • Required Scope: memory:read

  • When to use: check a profession exists and read its address and package before working with its lessons

Parameter

In

Type

Required

Default

Description

profession_code

path

string

yes

—

The profession's code

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.getProfession({ profession_code: "threads-content-creator" });
console.log(result);
// → 200 OK (GET /api/v1/memory/professions/{profession_code})

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

listProfessionWorkflows(profession_code, since?, limit?)

Pull the published workflow-library entries of a profession your brand is a member of, oldest first, by cursor.

  • HTTP Route: GET /api/v1/memory/professions/{profession_code}/workflows

  • Required Scope: memory:read

  • When to use: read the workflows your profession has published; pass the reply's `cursor` as `since` for the next page

Parameter

In

Type

Required

Default

Description

profession_code

path

string

yes

—

The profession's code

since

query

string

no

—

The `cursor` of the previous reply

limit

query

integer

no

100

Page size

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listProfessionWorkflows({ profession_code: "threads-content-creator", since: "2026-11-01T00:00:00Z", limit: 10 });
console.log(result);
// → 200 OK (GET /api/v1/memory/professions/{profession_code}/workflows)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

Delivered Workspace Memory, Export & Dev Desks

getDeliveredMemory(agent_id)

The exact MEMORY.md last delivered to one of the brand's agents, when every memory in it came from this brand.

  • HTTP Route: GET /api/v1/memory/my/agents/{agent_id}/delivered

  • Required Scope: memory:read

  • When to use: see exactly what one of your brand's agents was last given as MEMORY.md

Parameter

In

Type

Required

Default

Description

agent_id

path

string

yes

—

Agent workspace id, 1-255 letters, digits, '_' or '-'

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.getDeliveredMemory({ agent_id: "acme-sdr-001" });
console.log(result);
// → 200 OK (GET /api/v1/memory/my/agents/{agent_id}/delivered)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

exportMemories(format?, agent_id?)

Download the memories learned from this brand's own conversations, grouped by agent, as JSON or as one Markdown file.

  • HTTP Route: GET /api/v1/memory/my/export

  • Required Scope: memory:read

  • When to use: export your brand's memories, all agents or one (`agent_id`); `format: json` for data, `md` for a readable file

Parameter

In

Type

Required

Default

Description

format

query

enum

no

—

md (the route's default) for a Markdown file, json for structured data

agent_id

query

string

no

—

Export only this agent's memories

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.exportMemories({ format: "json", agent_id: "acme-sdr-001" });
console.log(result);
// → 200 OK (GET /api/v1/memory/my/export)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

listDeskMemories(format?, desk_ref, query?, kinds?, tags?, min_confidence?, importance?, status?, forgotten?, limit?, offset?)

List the memories a brand-owned dev desk has built up, by the desk's reference. `agent_id` and `origin_brand_id` are runtime-only: the gateway sets them from the desk and your token.

  • HTTP Route: GET /api/v1/memory/desks/{desk_ref}/memories

  • Required Scope: memory:read

  • When to use: read what one of your brand's dev desks has learned, with the same filters as listMemories

Parameter

In

Type

Required

Default

Description

format

query

enum

no

—

Reply rendering; json when omitted

desk_ref

path

string

yes

—

The desk's reference

query

query

string

no

—

Full-text match on title and body

kinds

query

string

no

—

Comma-separated kinds, e.g. "fact,decision"

tags

query

string

no

—

Comma-separated tags

min_confidence

query

number

no

—

Only memories at or above this confidence (0.0 to 1.0)

importance

query

enum

no

—

Only memories of this importance

status

query

string

no

active

Memory status to list; `active` by default

forgotten

query

boolean

no

False

true lists the memories people marked forgotten instead of the rest

limit

query

integer

no

20

Page size

offset

query

integer

no

0

Rows to skip; add `limit` for the next page

import { createOpvsClient } from '@opvs-ai/agentmemory';

const memory = createOpvsClient({ pat: process.env.OPVS_PAT! });
const result = await memory.listDeskMemories({ desk_ref: "desk_ops_01", format: "json", query: "pricing page annual billing" });
console.log(result);
// → 200 OK (GET /api/v1/memory/desks/{desk_ref}/memories)

Errors

Error

When

Resolution

401 Unauthorized

The PAT or session cookie is missing, malformed, expired, or revoked.

Verify active credentials with opvs -w opvs auth status or pass a valid OPVS_PAT.

403 Forbidden

The caller token lacks memory:read or a role-gated curator/profession membership check refused access.

Use a brand-scoped token holding memory:read and confirm required curator or profession membership.

404 Not Found

The referenced ID does not exist or belongs to another brand tenant.

Re-list or search within the active brand to obtain a valid in-brand identifier.

422 Unprocessable Entity

A path, query, or body parameter failed schema validation or range bounds.

Check parameter types and bounds in the table above and retry with valid arguments.

Did this answer your question?
Need help? support@opvs.aiChangelogLLM? Read llms.txt