jimfm/ov-claude

OpenViking Claude Memory Plugin (Scheme B)

Claude Code memory plugin built on OpenViking Session memory.

• Session data is accumulated during a Claude session (Stop hook).
• At SessionEnd, plugin calls session.commit() to trigger OpenViking memory extraction.
• Memory recall is handled by memory-recall skill.

Design choices in this version

• Mode: auto switch
  • Try HTTP first (from ov.conf server.host + server.port, health check /health)
  • Fallback to embedded local mode if server is unreachable
• Config: fallback chain
  • Checks ./ov.conf in project root first
  • Falls back to ~/.openviking/ov.conf if project config missing
  • Both support auto server detection
• Plugin state dir: ./.openviking/memory/

Structure

examples/claude-memory-plugin/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json
│   ├── common.sh
│   ├── session-start.sh
│   ├── user-prompt-submit.sh
│   ├── stop.sh
│   └── session-end.sh
├── scripts/
│   ├── ov_memory.py
│   └── run_e2e_claude_session.sh
└── skills/
    └── memory-recall/
        └── SKILL.md

Setup

This plugin requires an OpenViking configuration file. Choose one:

Option 1: Project-local config (recommended)

# Create ov.conf in your project root
cp $HOME/path-to-openviking/ov.conf ./ov.conf

Option 2: Global config (used for all projects)

# Set up global config (checked if project ov.conf missing)
mkdir -p ~/.openviking
cp $HOME/path-to-openviking/ov.conf ~/.openviking/ov.conf

The plugin will look for configuration in this order:

1. ./ov.conf (project root) — takes precedence
2. ~/.openviking/ov.conf (global) — fallback

Hook behavior

• SessionStart
  • Validate ./ov.conf
  • Auto-detect backend mode (http/local)
  • Create a new OpenViking session and persist plugin state
• UserPromptSubmit
  • Adds lightweight hint that memory is available
• Stop (async)
  • Parse transcript last turn
  • Summarize turn (uses claude -p --model haiku when available; fallback to local summary)
  • Append user + assistant summary to OpenViking session
  • Deduplicate by last user turn UUID
• SessionEnd
  • Commit OpenViking session to extract long-term memories

Skill behavior

memory-recall runs bridge command:

python3 .../ov_memory.py recall --query "<query>" --top-k 5

It searches:

• viking://user/memories/
• viking://agent/memories/

Then returns concise, source-linked memory summaries.

One-click E2E

Run a real Claude headless session end-to-end. The script auto-detects paths relative to its location:

bash ./scripts/run_e2e_claude_session.sh

Or provide custom source config and prompt (useful if your OpenViking setup is elsewhere):

bash ./scripts/run_e2e_claude_session.sh \
  $HOME/path-to-openviking/ov.conf \
  "Custom prompt here"

Example with absolute paths:

bash /path/to/ov-claude/scripts/run_e2e_claude_session.sh \
  $HOME/projects/OpenViking/ov.conf \
  "Test prompt"

What the script does:

• Creates a Python 3.11 virtual environment under /tmp (one-time dependency install).
• Generates a temporary project ./ov.conf from source config and injects HTTP server fields.
• Starts OpenViking HTTP server, runs a real claude -p session with this plugin, then triggers deterministic Stop + SessionEnd validation.
• Verifies session_state.json, ingested_turns >= 1, and session archive file creation.
• Restores original ./ov.conf when done.

Notes

• This MVP does not modify OpenViking core.
• If neither ./ov.conf nor ~/.openviking/ov.conf exists, hooks degrade safely and report status in systemMessage.
• State file: ./.openviking/memory/session_state.json
• Config fallback allows both project-specific and global setups
• All hooks use standard shell and Python stdlib — no external dependencies