OpenViking/examples/basic-usage/README.md

Basic Usage Example: OpenViking Python SDK

This example is the shortest path to understanding OpenViking's core Python SDK workflow: initialize a client, ingest a resource, browse the viking:// filesystem, retrieve context, and create a session that can later be committed into long-term memory.

It is intentionally SDK-first. If you want production deployment, shared access, or MCP client integration, use this example as the foundation and then move to the server and MCP guides linked below.

What This Example Covers

• HTTP SDK usage
• Resource ingestion from a remote URL
• Filesystem-style access with ls, tree, and read
• Retrieval with find, abstract, overview, and grep
• Session creation and message appending for memory workflows

Choose the Right Mode

OpenViking has two common integration paths:

Mode	Best for	Recommended?
HTTP server + SDK/CLI	Shared service, multi-session, multi-agent workloads	Yes, preferred for real deployments
MCP	Claude Code, Cursor, Claude Desktop, OpenClaw, and other MCP hosts	Yes, for tool-based client integration

For MCP specifically, follow the dedicated MCP Integration Guide.

Prerequisites

1. Python 3.10+
2. OpenViking installed:

pip install openviking-sdk --upgrade

3. A running OpenViking server

Quick Start

1. Run the Example Script

git clone https://github.com/volcengine/OpenViking.git
cd OpenViking/examples/basic-usage
python basic_usage.py

The script connects to a local OpenViking server:

from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://localhost:1933")
client.initialize()

See the dedicated Server Mode Quick Start for the recommended shared-service setup.

2. What the Script Demonstrates

basic_usage.py walks through the same sequence most applications need:

1. Initialize a client and verify health.
2. Add a resource from a URL.
3. Inspect the resulting viking://resources/... tree.
4. Wait for semantic processing.
5. Load L0/L1/L2 context with abstract, overview, and read.
6. Run retrieval with find.
7. Run literal content search with grep.
8. Create a session and append messages for later memory extraction.

Code Walkthrough

Initialization

Use the HTTP client when OpenViking runs as a separate service:

from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://localhost:1933")
client.initialize()

If server authentication is enabled, use a user_key for normal data access:

client = SyncHTTPClient(
    url="http://localhost:1933",
    api_key="<user-key>",
)

root_key is for administrative access. It does not directly work with tenant-scoped APIs such as add_resource, find, or ls unless you also pass account and user. See Authentication and Server Mode Quick Start.

Resource Ingestion

Add a URL, local file, or directory:

result = client.add_resource(
    path="https://example.com/docs",
)

result = client.add_resource(path="/path/to/manual.pdf")

result = client.add_resource(
    path="/path/to/repo",
    options={"instruction": "This is a Python web application"},
)

Imports return a task_id by default. Query client.get_task(result["task_id"]) and read summaries or search the imported content only after the task reaches completed. See Background Tasks for polling examples.

Filesystem Access

OpenViking organizes context as a virtual filesystem:

files = client.ls(uri="viking://resources/")
tree = client.tree(uri="viking://resources/my-project", level_limit=3)
content = client.read(uri="viking://resources/my-project/README.md")

This same URI model applies to memories and skills as well:

• viking://resources/
• viking://~/memories/
• viking://~/skills/

Retrieval

Use find for fast semantic search and search for more advanced retrieval:

results = client.find(
    query="how does authentication work",
    options={"target_uri": "viking://resources/my-project", "limit": 5},
)

results = client.search(
    query="database configuration and failure handling",
    options={"target_uri": "viking://resources/", "limit": 10},
)

Use tiered loading after retrieval:

uri = "viking://resources/my-project/docs/api.md"

abstract = client.abstract(uri=uri)
overview = client.overview(uri=uri)
content = client.read(uri=uri)

Use grep when you need literal text matching instead of semantic retrieval:

result = client.grep(
    uri="viking://resources/my-project",
    pattern="Agent",
    case_insensitive=True,
)
matches = result.get("matches", [])

Sessions and Long-Term Memory

The example script creates a session and appends messages:

session_info = client.create_session()
session_id = session_info["session_id"]

client.add_message(
    session_id=session_id,
    role="user",
    content="I prefer TypeScript over JavaScript",
)
client.add_message(
    session_id=session_id,
    role="assistant",
    content="Understood. I will use TypeScript where appropriate.",
)

To extract durable memories from that conversation, commit the session:

client.commit_session(session_id=session_id)

After commit, you can retrieve those memories through normal search APIs:

memories = client.find(
    query="user programming preferences",
    target_uri="viking://~/memories/",
)

Configuration

Create ~/.openviking/ov.conf with storage, embedding, and VLM settings. A minimal local setup looks like this:

{
  "server": { "host": "127.0.0.1", "port": 1933 },
  "storage": {
    "workspace": "~/.openviking/data"
  },
  "embedding": {
    "dense": {
      "provider": "openai",
      "api_key": "your-api-key",
      "model": "text-embedding-3-large",
      "dimension": 3072
    }
  },
  "vlm": {
    "provider": "openai",
    "api_key": "your-api-key",
    "model": "gpt-4o"
  }
}

You can also use Volcengine or Azure OpenAI. For current provider-specific examples, check the main README and the Configuration Guide.

Recommended Next Steps

• Configuration Guide: review the current config model before moving to shared deployments.
• Server Mode Quick Start: set up openviking-server properly.
• MCP Integration Guide: connect OpenViking to Claude Code, Cursor, Claude Desktop, or OpenClaw.
• Claude Code Memory Plugin: use OpenViking as long-term memory inside Claude Code.
• OpenCode Plugin: use OpenViking repository context and memory tools inside OpenCode.
• OpenClaw Plugin: integrate OpenViking with OpenClaw.

Troubleshooting

Issue	What to check
ImportError or local extension issues	Reinstall openviking; if developing from source, ensure local build dependencies are available.
Connection refused in HTTP mode	Start openviking-server and verify http://localhost:1933/health.
Tenant/auth errors	Prefer user_key for normal data APIs; use root_key only with explicit tenant headers.
Slow or empty search results right after ingestion	Query the import task by task_id and search after its status reaches completed.
Multiple clients or sessions competing for local storage	Use HTTP server mode instead of spinning up separate local processes.

License

Apache License 2.0