Memory

Memory is produced by session commit or explicit extraction, stored in the user memory namespace, and consumed through the content, file-system, and retrieval APIs.

Built-in Memory Types

Category	Location	Description
profile	user/memories/profile.md	User profile information
preferences	user/memories/preferences/	User preferences by topic
entities	user/memories/entities/	Important entities (people, projects)
events	user/memories/events/	Significant events
identity	user/memories/identity.md	Assistant identity and self-introduction
soul	user/memories/soul.md	Assistant principles, boundaries, style, and continuity
cases	user/memories/cases/	Trainable and evaluable task cases
trajectories	user/memories/trajectories/	Reusable operation contracts
experiences	user/memories/experiences/	Reusable execution insights
tools	user/memories/tools/	Tool usage knowledge and best practices
skills	user/memories/skills/	Skill execution knowledge and workflow strategies

These are the enabled built-in types. Deployments can extend or override them with custom memory templates.

---

API Reference

recall()

Search each memory type independently and assemble a bounded memory block that can be injected directly into Agent context. By default, recall searches events, entities, and preferences; the experiences quota defaults to 0 and must be enabled explicitly.

Parameter	Type	Required	Default	Description
query	string	Yes	-	Recall query
quotas	object	No	events=10, entities=10, preferences=3, experiences=0	Maximum results for each type
max_chars	integer	No	6500	Maximum rendered memory-block length
min_score	number	No	0.1	Minimum relevance score
peer_scope	string	No	all	actor searches only the current actor peer; all also searches global and other-peer memory
other_peer_penalty	number/object	No	Per-type defaults	Score penalty applied to results from other peers
render	boolean	No	true	Whether to produce the rendered memory block

HTTP API

POST /api/v1/search/recall
Content-Type: application/json

curl -X POST http://localhost:1933/api/v1/search/recall \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "query":"OpenViking API documentation preferences",
    "quotas":{"events":5,"entities":5,"preferences":3,"experiences":2},
    "max_chars":6500,
    "peer_scope":"all"
  }'

MCP

recall(
  query="OpenViking API documentation preferences",
  quotas={"events": 5, "entities": 5, "preferences": 3, "experiences": 2},
  max_chars=6500,
  peer_scope="all"
)

Response

{
  "status": "ok",
  "result": {
    "entries": [
      {
        "uri": "viking://user/default/memories/preferences/api-docs.md",
        "score": 0.82,
        "type": "preferences",
        "mode": "full",
        "rank": 1,
        "content": "The user prefers API documentation with HTTP, SDK, and CLI examples.",
        "origin": "self"
      }
    ],
    "rendered": "## Global Memory\n### Preferences\n[1] viking://user/default/memories/preferences/api-docs.md (score=0.8200)\nThe user prefers API documentation with HTTP, SDK, and CLI examples.",
    "stats": {
      "quotas": {
        "events": 5,
        "entities": 5,
        "preferences": 3,
        "experiences": 2
      },
      "roots": [
        "viking://user/default/memories"
      ],
      "searched": {
        "events": 2,
        "entities": 1,
        "preferences": 1,
        "experiences": 0
      },
      "returned": 1,
      "dropped": 0,
      "max_chars": 6500,
      "min_score": 0.1,
      "peer_scope": "all",
      "other_peer_penalties": {
        "events": 0.1,
        "entities": 0.1,
        "preferences": 0.02,
        "experiences": 0.02
      },
      "origins": {
        "actor_peer": 0,
        "self": 1,
        "other_peer": 0
      }
    }
  }
}

Field	Type	Description
entries	object[]	Structured matches selected by per-type quota and relevance
entries[].uri	string	Viking URI of the memory entry
entries[].score	number	Raw relevance score
entries[].type	string	events, entities, preferences, or experiences
entries[].mode	string	Rendering mode: full, summary, or uri
entries[].rank	integer	Rank within the memory type, starting at 1
entries[].origin	string	Source: actor_peer, self, or other_peer
entries[].content	string	Full content when mode=full; otherwise it may be omitted
entries[].summary	string	Summary used for degraded rendering; otherwise it may be omitted
entries[].abstract	string	Search-hit abstract; omitted when unavailable
rendered	string	Text bounded by max_chars and ready for Agent context injection; empty when render=false
stats	object	Effective quotas, roots, per-type search counts, returned and dropped counts, threshold, peer scope, and origin counts

The public Python, TypeScript, and Go SDKs and the ov CLI do not currently wrap type-quota recall, so this section shows only the HTTP tab and the existing MCP call.

Related Documentation

• Sessions - commit and extract
• Retrieval - search memory
• Content - read memory content