Tools
Openviking Hooks
By Production-grade memory hooks for all AI CLI clients (Claude Code, Codex, Gemini CLI, OpenClaw). Hybrid search, 5-scope system, content merge, auto-linking. Fork of Castor6/openviking-plugins.
README
# OpenViking Memory Hooks
Auto-recall + auto-capture hooks for [OpenViking](https://github.com/volcengine/OpenViking). Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw.
Fork of [Castor6/openviking-plugins](https://github.com/Castor6/openviking-plugins). Added scoping, hybrid search, dedup, and multi-CLI support.
## CLIs
| CLI | Recall | Capture |
|-----|--------|---------|
| Claude Code | UserPromptSubmit | Stop |
| Codex CLI | UserPromptSubmit | Stop |
| Gemini CLI | BeforeAgent | AfterAgent |
| OpenClaw | before_prompt_build | afterTurn |
All share one OV instance, one user, one memory pool. Agent-ID is just a tag.
## How it works
```
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ
โ Claude Code โ โ Codex CLI โ โ Gemini CLI โ โ OpenClaw โ
โโโโโโโโฌโโโโโโโ โโโโโโโโฌโโโโโโโ โโโโโโโโฌโโโโโโโ โโโโโโโโฌโโโโโโโ
โ โ โ โ
โ UserPrompt โ UserPrompt โ BeforeAgent โ before_prompt
โผ โผ โผ โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ auto-recall.mjs โ
โ โ
โ CWD โโโบ scope-resolver โโโบ 5 target URIs โ
โ โ โ
โ โโโโบ /search/find (semantic, per scope) โโโ โ
โ โโโโบ /search/grep (keywords) โโโค โ
โ โผ โ
โ RRF Merge โ
โ โ โ
โ ranking.mjs โโโโโโโโโโโโ โ
โ (source authority + backlinks) โ
โ โ โ
โ compaction.mjs โ
โ (~30% token reduction) โ
โ โ โ
โ scope hints โ
โ โผ โ
โ <relevant-memories> โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโดโโโโโโโโโโ
โผ โผ
Agent works On session end
โ โ
โ โผ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ auto-capture.mjs โ
โ โ โ
โ โ Content Merge (>0.85?) โ
โ โ โโ yes: append โ
โ โ โโ no: extract new โ
โ โ โ
โ โ Record Used (feedback) โ
โ โ Auto-Link (project) โ
โ โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโ
โ โ
โผ โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ OpenViking Server โ
โ (localhost:1933) โ
โ โ
โ viking://resources/ โ
โ โโโ system/ โ
โ โโโ infra/ โ
โ โโโ projects/<slug>/ โ
โ โโโ knowledge/ โ
โ โโโ tool-docs/ โ
โ viking://user/memories/ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## What this adds over Castor6
- **Scoping** โ 5 scopes (project, system, infra, knowledge, personal), CWD-based
- **Hybrid Search** โ semantic + grep + RRF merge
- **Content Merge** โ score >0.85 โ append to existing memory instead of duplicate
- **Record Used** โ tracks which recalls were useful, ranking improves over time
- **Auto-Linking** โ new memories get linked to active project
- **Compaction** โ regex-based, ~30% fewer tokens
- **Source Authority** โ verified memories rank higher
- **2 extra MCP tools** โ `memory_search` (glob/grep), `convert_to_markdown` (markitdown)
- **Session-Start Check** โ syncs project context to OV on first visit
## vs Castor6 Original
| | Castor6 | This fork |
|---|---|---|
| CLIs | Claude Code | + Codex, Gemini, OpenClaw |
| Search | Semantic only | + grep + RRF merge |
| Scoping | None | 5 scopes, CWD-based |
| Dedup | None | Content merge (>0.85) |
| Ranking | Score only | + source authority + backlinks |
| Compaction | None | Caveman (~30% reduction) |
| Relations | None | Auto-link to projects |
| Feedback | None | Record Used |
| MCP Tools | 4 | 6 |
## Install
```bash
./install.sh all # all CLIs
./install.sh claude-code # just Claude Code
./install.sh codex # just Codex
./install.sh gemini # just Gemini
./install.sh openclaw # just OpenClaw
```
Then edit `~/.openviking/<cli>-memory-plugin/config.json` โ set API key, account, user.
## Scopes
| Scope | URI | Active when |
|-------|-----|-------------|
| system | `viking://resources/system/` | Always |
| infra | `viking://resources/infra/` | No project, or infra CWD |
| project | `viking://resources/projects/<slug>/` | CWD in project dir |
| knowledge | `viking://resources/knowledge/` | Always |
| personal | `viking://user/memories/personal/` | Personal projects only |
Config: `shared/scope-config.json`
## Repo structure
```
shared/ โ scope-resolver, compaction, scope-config (all CLIs import these)
scripts/ โ hook scripts (auto-recall, auto-capture, bootstrap, config, debug)
servers/ โ MCP server (6 tools)
hooks/ โ hook definitions per CLI
config/ โ config templates per CLI (placeholder keys)
src/ โ TypeScript source
```
## Config
`~/.openviking/<cli>-memory-plugin/config.json`:
| Field | Default | What |
|-------|---------|------|
| `mode` | `local` | `local` or `remote` |
| `agentId` | `claude-code` | Tag, not namespace |
| `recallLimit` | `10` | Max memories per recall |
| `captureMode` | `semantic` | `semantic` or `keyword` |
| `debug` | `false` | Hook debug logging |
Override shared module path: `export OPENVIKING_HOME=/path/to/.openviking`
## License
Apache-2.0
tools
Comments
Sign in to leave a comment