Store and retrieve an agent’s notes

← Multi-model writes

The language tabs use earlier client interfaces. Check SDK versions and connection setup before running them.

Connect a note’s fields, embedding and searchable text through a shared ID. Vector metadata narrows searches to an agent or session.

Before you run it: Coordinate separate writes and deletes. Metadata filters do not replace access controls, and deleting a row does not delete its search entries.

Use the tenant-scoped HTTP connection described in the connection notes. In these snippets, ORIGINCHAIN_URL is the origin including https://, T is its tenant ID, and OC_TOKEN is its bearer token. Do not append these routes to a different Connect URL format.

Follow the exampleCopy Anchor Link

1. Register the memory schema.
2. Write the source note.
3. Write embedding and text using the same ID.
4. Filter the search and fetch the source note.

Set up the tableCopy Anchor Link

The composite index covers the most common read shape - "newest memories for this agent in this session".

# agent/memories.toml
namespace   = "agent"
table       = "memories"
primary_key = ["id"]

[[columns]]
name = "id"
ty   = "str"
required = true

[[columns]]
name = "agent_id"
ty   = "str"
required = true

[[columns]]
name = "session_id"
ty   = "str"
required = true

[[columns]]
name = "text"
ty   = "str"
required = true

[[columns]]
name = "ts_ms"
ty   = "u64"
required = true

# Composite index supports "all memories for this agent in this session,
# newest first" without a full scan.

[[indexes]]
name    = "by_agent_session_time"
columns = ["agent_id", "session_id", "ts_ms"]

The memory rowCopy Anchor Link

curl -X POST "$ORIGINCHAIN_URL/v1/tenants/$T/rows/agent.memories" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id":         "mem-77f2-001",
    "agent_id":   "agt-sales-east",
    "session_id": "thr-77f2",
    "text":       "Customer prefers contact between 09:00 and 11:00 IST.",
    "ts_ms":      1749500120000
  }'

The embedding with metadataCopy Anchor Link

Write agent_id and session_id in vector metadata as well as the row when the query needs those filters. A query without the intended filter can return other matching notes. Enforce access permissions separately; metadata is not an authorization system.

curl -X POST "$ORIGINCHAIN_URL/v1/tenants/$T/vector/agent.memories/put" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id":        "mem-77f2-001",
    "embedding": [0.0144, -0.0681, 0.0398, /* ... 768 floats ... */],
    "dim":       768,
    "metric":    "cosine",
    "metadata": {
      "agent_id":   "agt-sales-east",
      "session_id": "thr-77f2"
    }
  }'

The keyword indexCopy Anchor Link

curl -X POST "$ORIGINCHAIN_URL/v1/tenants/$T/fts/agent.memories/text" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "mem-77f2-001",
    "text":   "Customer prefers contact between 09:00 and 11:00 IST."
  }'

The embedding arrays are shortened illustrations. Generate the full vector with your chosen model, match dim to its length, and use that same model when embedding a search question. An embedding is a numeric representation used to compare meaning; OriginChainDB does not generate it in these write calls.

Handle separate writes and retriesCopy Anchor Link

These write calls commit separately. The documented SDKs do not provide automatic retry safety. A new SDK call can generate a new key. Retry reads with bounded backoff; for writes, confirm the endpoint supports deduplication and reuse a stable key, or reconcile the previous outcome first. See idempotency.

Important limits and checksCopy Anchor Link

• Include the metadata used by the query, and apply the intended filter. Enforce access controls separately.
• Split long conversations into useful passages before embedding them. Choose passage size by checking retrieval quality.
• Use the same embedding model and preprocessing at write and query time.
• When expiring a note, delete its row, vector and full-text entry separately. A row delete does not remove the other entries.

Expected resultCopy Anchor Link

Search the agent.memories collection using the filtered-vector pattern, keeping the same agent and session metadata as the write. A matching ID such as mem-77f2-001 identifies the source row to read. Verify its agent_id, session_id and text before using the note.

ContinueCopy Anchor Link

Continue to search within matching metadata.