Use OpenViking storage

The openviking long-term memory backend writes conversation messages to OpenViking user memory and retrieves entities, events, and preferences by user identity. It is available in VeADK 1.0.3 and later.

Runner.user_id is the end-user identifier that VeADK uses as the OpenViking peer_id for memory isolation. openviking_user_id is the OpenViking owner/context used to isolate memories for different applications or tenants within the same OpenViking service. The two are distinct concepts.

Example

The base installation includes openviking-sdk. Before running, provide an OpenViking service with user memory support and set DATABASE_OPENVIKING_URL, DATABASE_OPENVIKING_API_KEY, and DATABASE_OPENVIKING_USER_ID. Automatic and manual saves both send conversation content to that service; configure access and retention first

import os

from veadk import Agent
from veadk.memory.long_term_memory import LongTermMemory

memory = LongTermMemory(
    backend="openviking",
    app_name="support_app",
    backend_config={
        "index": "support_app",
        "url": "https://openviking.example.com",
        "api_key": os.environ["DATABASE_OPENVIKING_API_KEY"],
        # Optional; defaults to default when omitted
        "openviking_user_id": "support_app",
        # Optional; explicitly sets the memory policy; when omitted the OpenViking service applies its official default
        "memory_policy": {
            "self": {"enabled": False},
            "peer": {"enabled": True},
            "memory_types": ["entities", "events", "preferences"],
        },
    },
)

agent = Agent(
    long_term_memory=memory,
    auto_save_session=True,
)

Parameters

`LongTermMemory` parameters

Parameter	Type	Default	Description
`backend`	`str`	`opensearch`	Set to `openviking` to use OpenViking.
`backend_config`	`dict`	`{}`	Explicit OpenViking backend configuration.
`top_k`	`int`	`5`	Number of memories returned by each retrieval.
`index`	`str`	`""`	Application-name fallback; retrieval isolation depends on openviking_user_id and peer_id, not index alone
`app_name`	`str`	`""`	Application name and fallback value for `index`.
`user_id`	`str`	`""`	Deprecated compatibility field. The runtime user comes from the session or `Runner.user_id`.

OpenViking backend parameters

Parameter	Type	Default	Description
`index`	`str`	Supplied by `LongTermMemory`	Application or memory index name. It cannot be empty.
`openviking_config`	`OpenVikingConfig`	Read from `DATABASE_OPENVIKING_*`	OpenViking service configuration.
`url`	`str`	`DATABASE_OPENVIKING_URL`	OpenViking service URL. Required.
`api_key`	`str`	`DATABASE_OPENVIKING_API_KEY`	OpenViking API key. Required.
`openviking_user_id`	`str`	`DATABASE_OPENVIKING_USER_ID` or `default`	OpenViking owner/context used to build the memory path. Allowed characters: letters, digits, `.`, `_`, `@`, `-`; cannot be `.` or `..`.
`memory_policy`	`dict \| None`	`OpenVikingConfig.memory_policy` / `None`	OpenViking memory extraction policy. When unset, no policy is sent to OpenViking and the service applies its official default.
`peer_id_resolver`	`Callable \| None`	Uses `user_id`	Maps `app_name` and `user_id` to an OpenViking peer ID.
`timeout`	`float`	`30`	OpenViking request timeout in seconds.

By default, user_id becomes the peer ID and may contain only letters, digits, periods, underscores, @, and hyphens. Pass peer_id_resolver to customize this mapping. When openviking_user_id is not configured, VeADK checks DATABASE_OPENVIKING_USER_ID and falls back to default, emitting a warning. Set it explicitly for each application or tenant to avoid mixing memories from different applications under the same default path. When memory_policy is unset, VeADK sends no policy to OpenViking and the OpenViking service applies its official default. To explicitly control the extraction scope and isolation, pass a valid memory_policy whose structure follows the OpenViking session API. For example:

{"self": {"enabled": false}, "peer": {"enabled": true}, "memory_types": ["entities", "events", "preferences"]}

This example disables self-memory extraction and only extracts entities, events, and preferences from the counterparty; the actual accepted values and fields depend on what the OpenViking service supports.

Setting auto_save_session=True writes conversation data to an external OpenViking service. Confirm that data processing, access control, and retention meet your requirements before enabling it.

Environment variables

Environment variable	Default	Description
`DATABASE_OPENVIKING_URL`	None	OpenViking service URL.
`DATABASE_OPENVIKING_API_KEY`	None	OpenViking service-owner API key.
`DATABASE_OPENVIKING_USER_ID`	`default`	OpenViking owner/context ID.
`DATABASE_OPENVIKING_MEMORY_POLICY`	None (server default)	JSON string for the long-term memory `memory_policy`; when unset, no policy is sent to OpenViking and the service applies its official default.

Customize user mapping

Multi-tenant applications can provide peer_id_resolver to combine the application and user into one isolation key:

import os

from veadk.memory.long_term_memory import LongTermMemory


def resolve_peer_id(app_name: str, user_id: str) -> str:
    return f"{app_name}-{user_id}"


memory = LongTermMemory(
    backend="openviking",
    backend_config={
        "index": "support_app",
        "url": "https://openviking.example.com",
        "api_key": os.environ["DATABASE_OPENVIKING_API_KEY"],
        "peer_id_resolver": resolve_peer_id,
    },
)

The returned ID cannot be empty. It may contain only letters, digits, periods, underscores, @, and hyphens, and cannot be . or ... Changing the mapping after deployment leaves existing memories under the old peer path, so later retrievals may no longer find them.

Verify writes and retrieval

After configuring the dependencies and credentials on this page, run this standalone example. It saves user text and searches for that user directly without calling a conversation model

import asyncio

from google.adk.events import Event
from google.adk.sessions import Session
from google.genai import types
from veadk.memory.long_term_memory import LongTermMemory

async def main():
    memory = LongTermMemory(backend="openviking", index="ltm_demo")
    session = Session(
        id="memory_check", app_name="ltm_demo", user_id="user_42",
        events=[Event(author="user", content=types.Content(
            role="user", parts=[types.Part(text="My preferred language is Chinese")]
        ))],
    )
    await memory.add_session_to_memory(session)
    result = await memory.search_memory(
        app_name="ltm_demo", user_id="user_42", query="preferred language"
    )
    for entry in result.memories:
        print(entry.content)

asyncio.run(main())

Results should contain the saved language preference. Managed services may extract memories asynchronously, so a completed write does not guarantee immediate retrieval. An empty result can also indicate permission, network, or service failure; check error logs and service records. The save method does not return a success Boolean

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Example

Parameters

`LongTermMemory` parameters

OpenViking backend parameters

Environment variables

Customize user mapping

Verify writes and retrieval

​Example

​Parameters

​LongTermMemory parameters

​OpenViking backend parameters

​Environment variables

​Customize user mapping

​Verify writes and retrieval

Example

Parameters

`LongTermMemory` parameters

OpenViking backend parameters

Environment variables

Customize user mapping

Verify writes and retrieval