claude-code-openviking

v0.2.1

Published

12 days ago

OpenViking long-term memory integration for Claude Code — auto-recall, auto-capture, and MCP tools

0High
0Medium
0Low

billzhao

claude-code openviking memory mcp auto-recall long-term-memory

openviking-claude-code

OpenViking long-term memory integration for Claude Code.

Give Claude Code persistent memory across sessions — auto-recall past context, auto-capture new learnings.

English | 中文

English

What is this?

openviking-claude-code connects Claude Code to an OpenViking server for long-term memory. Once installed:

Auto-recall: Every message triggers a memory search — relevant past context is injected automatically
Auto-capture: Every Claude response is silently sent to OpenViking for memory extraction
MCP tools: memory_recall, memory_store, memory_forget available for manual use

v0.2.0 — Tiered Memory

The recall system now leverages OpenViking's native L0/L1/L2 context layers:

Split-space search — Searches user preferences and agent experience memories separately, then merges results. Ensures both types surface.
L0/L1 tiered injection — Top-3 highest-scoring memories inject L1 overview (~300 tokens each) for rich context. Remaining memories inject L0 abstract (~50 tokens each) for broad coverage.
3x coverage — Same 2000-token budget now covers ~20 memories instead of 6.
Smart capture filtering — Trivial conversations (< 2 turns or very short responses) are skipped, reducing noise in stored memories.

Quick Start

npx claude-code-openviking

You'll be asked for your OpenViking server URL and API key. That's it.

Non-Interactive

npx claude-code-openviking --url http://your-server:1933 --key your-api-key

What Gets Installed

| Component | Location | Purpose | |---|---|---| | auto-recall.cjs | ~/.claude/hooks/openviking/ | Search memories on every UserPromptSubmit | | auto-capture.cjs | ~/.claude/hooks/openviking/ | Capture conversation on every Stop (async) | | mcp-server.cjs | ~/.claude/hooks/openviking/ | MCP stdio server for memory tools | | Hook config | ~/.claude/settings.json | Registers hooks with Claude Code | | MCP config | .mcp.json (current directory) | Registers MCP server |

How It Works

You send a message
  ↓
auto-recall hook fires
  → searches user memories + agent memories + global (parallel)
  → merges & deduplicates by URI
  → top-3 inject L1 overview (rich), rest inject L0 abstract (compact)
  ↓
Claude sees your message + tiered memories → responds
  ↓
auto-capture hook fires (async)
  → quality gate: skips if < 2 turns or assistant text < 50 chars
  → sends conversation to OpenViking for memory extraction

Configuration

All settings use environment variables (with defaults from setup):

| Variable | Description | |---|---| | OPENVIKING_BASE_URL | OpenViking server URL | | OPENVIKING_API_KEY | API key for authentication | | OPENVIKING_AGENT_ID | Agent identifier (default: claude-code) |

MCP Tools

| Tool | Description | |---|---| | memory_recall | Search memories by query | | memory_store | Store text as memory | | memory_forget | Delete a memory by URI or search query |

Uninstall

npx claude-code-openviking --uninstall

Removes hooks and settings entries. MCP config (.mcp.json) left for manual cleanup.

Author

Bill Zhao — LinkedIn | GitHub

Credits

OpenViking — Long-term memory backend
Claude Code — The AI coding assistant

License

MIT

中文

这是什么？

openviking-claude-code 为 Claude Code 接入 OpenViking 长期记忆服务。安装后：

自动召回：每条消息自动搜索记忆，注入相关上下文
自动捕获：每次回复后静默发送对话到 OpenViking 提取记忆
MCP 工具：memory_recall、memory_store、memory_forget 可手动调用

v0.2.0 — 分层记忆

召回系统现在利用 OpenViking 原生的 L0/L1/L2 上下文分层：

分空间搜索 — 分别搜索用户偏好和 agent 经验记忆，合并结果，确保两类记忆都能浮现
L0/L1 分层注入 — 前 3 条高分记忆注入 L1 概要（详细），其余注入 L0 摘要（精简）
3 倍覆盖 — 同样 2000 token 预算，覆盖 ~20 条记忆（之前只有 6 条）
智能捕获过滤 — 跳过过于简短的对话（< 2 轮或回复太短），减少噪音记忆

快速安装

npx claude-code-openviking

输入 OpenViking 服务器地址和 API key 即可。

非交互安装

npx claude-code-openviking --url http://your-server:1933 --key your-api-key

安装了什么

| 组件 | 位置 | 功能 | |---|---|---| | auto-recall.cjs | ~/.claude/hooks/openviking/ | 每条消息自动搜索记忆 | | auto-capture.cjs | ~/.claude/hooks/openviking/ | 每次回复后异步捕获对话 | | mcp-server.cjs | ~/.claude/hooks/openviking/ | MCP 工具服务 | | Hook 配置 | ~/.claude/settings.json | 注册 hooks | | MCP 配置 | .mcp.json（当前目录） | 注册 MCP server |

工作流程

你发一条消息
  ↓
auto-recall 触发 → 搜索 OpenViking → 注入相关记忆
  ↓
Claude 看到你的消息 + 记忆 → 回复
  ↓
auto-capture 触发（异步）→ 对话发到 OpenViking
  ↓
OpenViking 提取并存储记忆，供未来召回

卸载

npx claude-code-openviking --uninstall

作者