memory

Read Graph

Bounded read of the concept-association graph around seeds (core#630).

Distinct from /memory/read's expanded_concepts (names only, discarded weights): this returns the actual hebbian_edges rows — weight, valence, count — for a caller-supplied neighbourhood, never the whole org's graph (PostgresStorage.load_hebbian_edges stays reserved for the single-tenant WS viz snapshot it was built for). Same org resolution and auth/scope as /memory/read — a read-only op, require_write=False.

An unknown seed (or one whose edges all fall below min_weight) simply contributes nothing: an all-unknown seeds list is a 200 empty graph, not a 404 — same "absence is not an error" contract as /memory/recent.

req.domain reaches _resolve_target_org exactly like /memory/read's does: an xroom:<room_id> value resolves to that room's OWN storage bucket (after the membership/scope check) — a real change of which org's edges get read, not a filter within one org. Any other value is inert (hebbian_edges has no domain column), same as passing none.

post/api/v1/memory/graph

Request

  • Base URL: https://core.mnemoverse.com
  • URL: https://core.mnemoverse.com/api/v1/memory/graph
  • Auth: one of:
    • API key in header X-Api-Key
    • HTTP bearer

Request body

seedsstring[] required

Concept names to center the graph on. 1-20 items, each at most 200 characters (the VARCHAR(200) width of hebbian_edges.source_concept/target_concept — a longer string can never match a stored concept).

depthinteger

Hop count from the seeds. depth=1 returns only edges touching a seed directly; depth=2/3 walk further, one hop per level. Each hop is independently bounded server-side by a per-hop row cap (see truncated). When min_weight is null AND this REQUESTED depth is >= 2, EVERY hop of the walk — including the first, hop 0 — floors the edge weight at 0.05 (reported back as min_weight_applied), so an unfiltered multi-hop walk from a hub concept cannot fan out across an org's whole graph before limit ever applies, and a depth=2 request cannot return a direct seed edge the floor would otherwise have excluded one hop later. An EXPLICIT min_weight (including 0.0) is honoured at every hop instead, with no server override.

domainstring nullable

Same mechanism as /memory/read, not a filter over one org's edges: an xroom:<room_id> value resolves (after the membership/scope check) to that ROOM's own storage bucket, so the graph is read from the room's hebbian_edges rows instead of the caller's own — this is NOT inert. Any other value (or null) IS inert: hebbian_edges has no domain column, so a plain domain string does not narrow which edges/atoms count — it has the same effect as omitting the field entirely.

min_weightnumber nullable

Drop edges below this weight. null = no caller-supplied floor at depth 1; when the REQUESTED depth is >= 2, the server applies its own floor (0.05, see depth) at every hop of the walk, including hop 0 — reported back as min_weight_applied. An EXPLICIT value (including 0.0) is honoured at EVERY hop with no server override, so min_weight=0.0 at depth>=2 really does return every edge down to weight 0.

limitinteger

Maximum number of edges to return. Mirrors ReadRequestSchema.top_k's bounds.

Example request

{
  "depth": 1,
  "limit": 100,
  "seeds": [
    "rotation",
    "symmetry"
  ]
}

Response

Successful Response

truncatedboolean required

True when either a per-hop server-side cap or the request's limit cut the walk short — the graph may hold more edges than are reported here.

min_weight_appliednumber required

The weight floor actually used at EVERY hop of the walk. Equal to the request's min_weight when it was set (an explicit value, including 0.0, is never overridden); equal to the server floor 0.05 when the request left min_weight null and the REQUESTED depth was >= 2 (applied from hop 0 onward, not just hop 1 onward); equal to 0.0 when it was null and depth == 1.

Example response

{
  "edges": [
    {
      "count": 3,
      "source": "rotation",
      "target": "symmetry",
      "updated_at": "2026-09-24T00:00:00Z",
      "valence": 0.1,
      "weight": 0.8
    }
  ],
  "min_weight_applied": 0,
  "nodes": [
    {
      "concept": "rotation",
      "degree": 1
    },
    {
      "concept": "symmetry",
      "degree": 1
    }
  ],
  "truncated": false
}

Changes

No recorded changes to this operation across all 1 revision of this API.