OpenViking Gateway: Enable Agentic Memory for Any AI Client Without Plugins

Introduction

OpenViking Gateway is a proxy that sits between any compatible AI client (chat apps, scripts, low-code platforms) and model services. It equips the model with Agentic memory —automatic recall of relevant past conversations, on-demand search and read of stored memories, and automatic extraction and saving of new information from each dialogue. Clients do not need to install OpenViking plugins or implement memory logic themselves; they only change two settings: the model Base URL (to the gateway address /gateway) and the API Key (to a gateway key issued in Studio).

Three Core Capabilities

Automatic recall : On each new user message, the gateway queries relevant memories and prepends them to the request so the model answers with context.

On-demand search and read : The model can invoke OpenViking tools to search memories and open original conversation snippets for verification. The gateway executes these tools; the client needs no tool support.

Automatic saving and summarization : When enabled, the gateway extracts useful information from the dialogue and stores it. For long conversations it can ask the model to generate a summary, reducing history size in subsequent requests.

Integration: Two Configuration Changes

Assuming the gateway is already deployed, a compatible client only updates:

Base URL : Change the model endpoint to the gateway address (service URL + /gateway).

API Key : Replace the model API key with a gateway key issued in Studio.

No plugin installation or custom memory code is required. Claude Code additionally needs an environment variable to distinguish its background requests (see deployment guide). Studio is the gateway's admin UI for configuring upstreams, memory policies, and allowed tools.

Supported Clients

The gateway targets clients that allow custom model endpoints and send full chat history. Verified working with memory read/write: Claude Code , Codex CLI , OpenAI Python SDK . Cherry Studio (pure chat mode) can use memory tools. Other clients require per-environment validation. Clients that only use subscription login or vendor-hosted model calls are not supported.

Architecture Overview

Deployment modes : Embedded in OpenViking Server (shared port) or standalone openviking-gateway connecting to an existing OpenViking service (including Volcano Engine hosted). Both use /gateway path.

Relation to OpenViking : Gateway calls only public OpenViking APIs; vectorization and memory extraction happen inside OpenViking.

Data location : Conversations and memories reside in OpenViking. Gateway stores only two local SQLite files: one for upstreams/keys/config, one for dialogue state (idle 30 days expiry). Encryption, deletion, isolation are documented separately.

Failure behavior : If OpenViking is down, chat continues without memory; writes retry automatically. If gateway stops (embedded mode = OpenViking Server stops), all proxied model calls fail.

Access control : Users issue gateway keys in Studio; admins can issue on behalf of users. Each key binds one OpenViking user, one context configuration (recall budget, write-back toggle, allowed tools), and a set of upstreams (model service URLs and keys).

Conversation Flow After Integration

The gateway automatically identifies the same conversation. Only user messages trigger recall; tool steps and auxiliary requests do not. Compressed history before the cutoff is no longer sent to the model; the model can use OpenViking tools to fetch original text from the session.

Agentic Memory via OpenViking Tools

Auto-recall is the gateway guessing what the model needs; with OpenViking tools the model decides what to search, read, and write. Tools are executed by the gateway—clients declare none. In a single reply:

Multi-step tool calls : Gateway intercepts model's OpenViking tool calls, executes them with the user's OpenViking credentials, returns results to the model, repeats until the model stops calling. Client receives one coherent reply.

Client tools still work : OpenViking tools and client-native tools (e.g., Bash) can be used in the same reply. Client tool calls pass through to the client for execution with its usual permission prompts.

Next turn remembers tool round-trips : Tool calls and results are not in client history; gateway stores them and replays them in the next turn so the model knows what it looked up, and prompt caching remains intact.

Available Tools

Tools come from the connected OpenViking service's tool list (prefixed openviking_), changing with server versions. Write/import/delete/permission-change tools are unchecked by default; others are checked by default (including future additions—review list before enabling).

Deployment: Two Paths

Both paths use the same client address ( service URL/gateway) and same two config changes. Detailed steps in official docs: https://docs.openviking.ai/zh/guides/22-gateway-operations.

Prerequisites

OpenViking ≥ 0.5.1 installed locally with embedding and VLM configured.

Volcano Ark API Key; Path B also needs your OV User API Key.

Claude Code installed, claude and curl available.

Commands for macOS/Linux terminals, default localhost-only. Upgrade by re-running in original environment:

python -m pip install --upgrade openviking

Path A: Local OV (Embedded Gateway)

Gateway shares port with existing OV; address http://127.0.0.1:1933/gateway.

A1 Enable Gateway

openviking-server init

Select Update gateway (now: disabled) with arrow keys, press Enter. Do not confirm default Start over (reconfigures everything).

At Enable OpenViking Gateway on the same port? enter y.

At Save configuration? press Enter; backup saved as ov.conf.bak.

At Validate the setup now? enter n (gateway validated later).

If OV already running, choose N at Start the server now? and restart per A2; else choose y to start.

Default config: ~/.openviking/ov.conf. Custom path: OPENVIKING_CONFIG_FILE=/path/ov.conf openviking-server init. Self-hosted api_key services that forbid user upstream config must save the generated ovgm_… management key.

A2 Restart and Verify

Stop existing service ( Ctrl-C if foreground, or via process manager), then start:

openviking-server --config ~/.openviking/ov.conf

In another terminal:

curl -s http://127.0.0.1:1933/health; echo
curl -s http://127.0.0.1:1933/gateway/v1/models; echo

Success: first returns "status":"ok"; second returns 401 / Invalid gateway key (gateway mounted, just no key). 404 means gateway not enabled or not restarted.

A3 Enter Studio

Open http://127.0.0.1:1933/studio/.

First connection: choose Open Source Service → Add new service address , manually enter http://127.0.0.1:1933, click Next (gray placeholder doesn't count).

Local dev mode: leave User API Key empty, click Verify Connection → Enter Studio . Self-hosted api_key services enter user API key here.

Select OpenViking Gateway on left, then proceed to Common Configuration.

Path B: Volcano Hosted OV (Standalone Gateway)

Run gateway locally, connect to hosted OV; memories stay in hosted OV. Gateway address http://127.0.0.1:1935/gateway.

B1 Initialize Standalone Gateway

openviking-gateway init

OpenViking server URL

: https://api.vikingdb.cn-beijing.volces.com/openviking. Listen host: press Enter for 127.0.0.1. Listen port: press Enter for 1935. Require a management key to change upstreams and profiles?: enter y.

Save the generated ovgm_… management key (shown once). Config written to ~/.openviking/gateway.conf.

B2 Start and Verify

Start gateway (keep terminal running): openviking-gateway Check: curl -s http://127.0.0.1:1935/health Success: returns "service":"openviking-gateway", openviking_url matches hosted address, openviking.status=ok, auth_mode=api_key.

B3 Login and Unlock Editing

Open http://127.0.0.1:1935/studio/.

Paste your OV API Key (not management key), click Login .

Click Enter gateway management key , paste the ovgm_… key from B1, click Unlock .

Success: header shows "Can modify upstreams and context configs". Closing tab re-locks.

Common Configuration & Client Onboarding

Both paths continue in Studio → OpenViking Gateway page.

Add Model Upstream

Click Upstreams → Add Upstream .

Name: "Volcano Ark Anthropic"; Provider: Volcano Ark ; Protocol: Anthropic Messages .

Confirm Base URL: https://ark.cn-beijing.volces.com/api/compatible; keep Append protocol path enabled.

API Key provided by : choose "Gateway keeps API Key", enter Ark API Key .

Model: deepseek-v4-1-flash-261017 (press Enter to tag), click Add Upstream .

Success: upstream appears with the model. Use any model your account supports with Anthropic Messages protocol.

Configure Auto Memory

Click Context Config . Path A: New Config , name "Quick Test (30s)"; Path B: Create with Recommended Settings , then edit generated "Default".

Enable Recall Memory and Save Conversation .

Set Save Conversation → Latest Reply Wait Time to 30 seconds for quick verification (default 600s for production).

Recall Memory → Timeout : Path A keep 2s ; Path B set 8s per tutorial.

Click Create Config or Save . Changes apply only to new conversations.

Issue Client Key

Click Keys → Issue Key , name "Claude Code Demo".

Path A dev mode auto-binds default identity; Path B paste your OV User API Key (root key not accepted).

Context Config: select the one just saved; Upstreams: check Volcano Ark Anthropic ; Allowed Models: leave empty.

Click Issue Key , immediately copy and save ovgw_… (shown once). One key per person—do not share.

Connect Claude Code

In the terminal running Claude Code (use a clean config dir, disable built-in memory):

export CLAUDE_CONFIG_DIR=~/.claude-gateway-demo
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
unset ANTHROPIC_API_KEY

Set gateway address, key, and model (Path B: change 1933 to 1935; do not append /v1):

export ANTHROPIC_BASE_URL=http://127.0.0.1:1933/gateway
export ANTHROPIC_AUTH_TOKEN='ovgw_replace_with_your_full_gateway_key'
export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1
export ANTHROPIC_MODEL=deepseek-v4-1-flash-261017
export ANTHROPIC_DEFAULT_HAIKU_MODEL=$ANTHROPIC_MODEL
export ANTHROPIC_DEFAULT_SONNET_MODEL=$ANTHROPIC_MODEL
export ANTHROPIC_DEFAULT_OPUS_MODEL=$ANTHROPIC_MODEL

Test connection:

claude -p "Answer in one sentence: what is 1+1?"

Success: normal answer. No Claude subscription login needed; don't use subscription token. If model name unrecognized but answers anyway, continue verification.

Verify Auto Memory

Use same project directory and same gateway key. First save a convention, then verify in a brand-new session.

Write Project Convention

Run claude in example project dir (trust only safe dirs), then input:

Remember: this project uses pnpm only, no npm; commit messages in English. Do not write these conventions to project files, just reply confirmed.

After reply, type /exit , wait ~1 minute (30s save wait + extraction time; not guaranteed exactly 1 minute).

New Session Verification

Run claude again, do not use --resume , input:

Help me add a lodash dependency to this project, tell me the command, don't execute yet.

Expected: model replies pnpm add lodash , not npm.

Confirm Gateway Recall Happened

In Claude Code type /status, copy Session ID .

In Studio, click OpenViking Gateway page top Request Logs (not left Activity logs).

Search Session ID, inspect the first "New Message" of the new session.

Success: request succeeded, save normal, Memory List shows +N ; expand details to see Anthropic upstream and recalled memories. Do not rely solely on model saying "I remembered". Start with one familiar client and one real project convention; follow the steps to verify save and recall. Make the next conversation require one less background re-explanation and take one more concrete step forward.