Add Claude Desktop Memory Integration Example Under examples/Claude-Desktop

[itzsamehfawzi]

This PR adds a full Claude Desktop memory‑integration example under examples/Claude-Desktop/, following the project’s contribution guidelines and the maintainer’s request to place Claude‑related examples inside the examples directory rather than the main README.

What’s included
A complete working integration between OpenViking and Claude Desktop

Automatic memory recall before Claude Code prompts

Automatic memory extraction and commit after each session

Windows‑native watchdog for self‑healing restarts

Windows Task Scheduler automation (autosave + health checks)

Embedding selector with Ollama‑first + Jina fallback

A 26‑point verification script to validate the integration

A dedicated Markdown example file documenting usage and setup

Why this belongs in examples/Claude-Desktop/
This integration is a standalone example demonstrating how to connect Claude Desktop to OpenViking’s memory engine.
It does not modify the core library and fits the structure used for other Claude‑related examples.

Folder structure
Code
examples/
Claude-Desktop/
openviking-claude-desktop.md

Notes
No changes were made to the main README.

All files are isolated to the example folder.

The branch contains only documentation + example code, no core logic changes.

Let me know if you prefer a different folder name or want the example split into submodules.

[itzsamehfawzi]

Hi @qin-ctx,
I’ve added the full Claude Desktop memory integration under examples/Claude-Desktop/ as requested.
The README changes were removed, and all integration files are now contained within the example folder along with a dedicated Markdown guide.

Please let me know if you’d like the folder renamed, reorganized, or split into smaller components. Happy to adjust anything.

Thanks for the guidance.

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🏅 Score: 85

🧪 No relevant tests

🔒 No security concerns identified

✅ No TODO sections

🔀 Multiple PR themes Sub-PR theme: Add MCP bridge and watchdog server files Relevant files: examples/Claude-Desktop/server/openviking-bridge.py examples/Claude-Desktop/server/openviking-mcp.py examples/Claude-Desktop/server/openviking-watchdog.py Sub-PR theme: Add Claude Code hook scripts Relevant files: examples/Claude-Desktop/hooks/ov_session.py examples/Claude-Desktop/hooks/ov-recall.js examples/Claude-Desktop/hooks/ov-capture.js

⚡ Recommended focus areas for review Hardcoded Python executable path The watchdog uses a hardcoded path to Python313, which may fail if the user has a different Python version installed. PYTHON_EXE = os.path.join(os.environ["USERPROFILE"], "AppData", "Local", "Programs", "Python", "Python313", "python.exe") Missing directory creation for logs The script tries to write to a log file without ensuring the parent directory exists first, which could cause a silent failure. LOG_FILE = HOME / ".claude-memory" / "logs" / "session-hooks.log" STATE_FILE = HOME / ".claude-memory" / ".session_state.json" HEADERS = { "Content-Type": "application/json", "Authorization": "Bearer " + OV_API_KEY, "x-api-key": OV_API_KEY, "x-openviking-user": "default", "x-openviking-account": "default", } def log(msg): ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S") line = "[{}] {}".format(ts, msg) print(line) try: with open(LOG_FILE, "a", encoding="utf-8") as f: f.write(line + "\n") except Exception: pass

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[itzsamehfawzi]

🔀 Multiple PR themes

Sub-PR theme: Add MCP bridge and watchdog server files
Relevant files:

• examples/Claude-Desktop/server/openviking-bridge.py
• examples/Claude-Desktop/server/openviking-mcp.py
• examples/Claude-Desktop/server/openviking-watchdog.py

Sub-PR theme: Add Claude Code hook scripts
Relevant files:

• examples/Claude-Desktop/hooks/ov_session.py
• examples/Claude-Desktop/hooks/ov-recall.js
• examples/Claude-Desktop/hooks/ov-capture.js

Thanks for the automated analysis. Regarding the “Multiple PR themes” note:

Why the PR contains multiple file groups
This example requires several coordinated components to demonstrate a complete Claude Desktop → OpenViking memory workflow. The files fall into two natural groups:

1. MCP bridge + watchdog server
   server/openviking-bridge.py

server/openviking-mcp.py

server/openviking-watchdog.py

These files work together to:

expose OpenViking memory operations via MCP

maintain a persistent background process

auto‑restart on failure

provide a stable bridge for Claude Desktop

2. Claude Code hook scripts
   hooks/ov_session.py

hooks/ov-recall.js

hooks/ov-capture.js

These scripts integrate with Claude Desktop to:

recall memory before each coding session

capture new memory after each session

pass data through the MCP bridge

Why they belong in a single PR
All of these files are part of one cohesive example.
The example does not modify core OpenViking logic — it simply demonstrates:

“How to connect Claude Desktop to OpenViking’s memory engine end‑to‑end.”

Splitting these into separate PRs would break the example and make it incomplete.

Summary
The PR contains multiple file groups, but they are all part of one unified example.

Each group supports a different layer of the integration (MCP bridge vs. Claude hooks).

All files are isolated under examples/Claude-Desktop/ and do not affect core code.

Happy to reorganize or split folders if you prefer a different structure.

[t0saki]

Thanks for putting this together — there's clearly a lot of care here, and a few things are genuinely well done: the REST endpoints all line up with the current server API, the error handling degrades gracefully when the server is down, and the docs/troubleshooting/verification work shows real effort. 🙏

That said, I think the PR needs a significant rework before it can land, mostly for structural reasons rather than code-quality ones. Sharing the main points so we can find the right shape together:

1. Scope overlaps with what we already ship. OpenViking already provides:

• An official Claude Code plugin under examples/claude-code-memory-plugin/, which does the same auto-recall (UserPromptSubmit) + auto-capture (Stop/SessionEnd) loop, plus token budgeting, CJK-aware estimation, and per-session isolation.
• A first-party MCP capability, so the hand-rolled openviking-bridge.py / openviking-mcp.py JSON-RPC servers re-implement something we already offer. I'd suggest dropping both — they add maintenance surface without adding capability over the existing MCP server.

2. The title says "Claude Desktop," but ~half the code is Claude Code. ov-recall.js and ov-capture.js are Claude Code hooks (UserPromptSubmit / Stop); Claude Desktop has no hook mechanism — it only consumes MCP. The two integration models are conceptually different and shouldn't be bundled under one folder. Since the Claude Code side is already covered by our official plugin, a Claude Desktop example would ideally be MCP-only — and given the point above, that may not need new code at all.

3. Repo hygiene. The PR vendors an entire standalone-repo scaffold into examples/Claude-Desktop/: its own LICENSE, NOTICE, LICENSES/, CONTRIBUTING.md, .gitignore, .github/ISSUE_TEMPLATE/, and .github/workflows/verify.yml. The nested license/contributing files duplicate the repo root, and the workflow won't actually run (GitHub only reads workflows from the repo-root .github/workflows). These should be removed so the example stays a self-contained subfolder.

4. Configuration is hardcoded. OV_USER / OV_ACCOUNT are pinned to "default", the port to 1933, and the key defaults to "YOUR_LOCAL_API_KEY", with nothing reading from ovcli.conf / env. Also, requests send both Authorization: Bearer and x-api-key — we're standardizing on Authorization: Bearer, so the x-api-key header can be dropped.

5. Platform coupling. The ~7 PowerShell scripts (watchdog, Task Scheduler registration, health alerts) and the Windows 11 / Python 3.13 / Node 20 pinning make this hard for the project to maintain or test cross-platform. If the watchdog/scheduler pieces are valuable, they'd fit better as an optional section in the troubleshooting docs rather than as core example code.

A couple of smaller correctness notes for whenever the recall path gets revisited: the single global ~/.claude-memory/.session_state.json means concurrent Claude Code windows will clobber each other's session, and the recall hook records the user turn but never the assistant turn, so commits only see the user side.

If you'd like to keep contributing here, the most useful direction would probably be a minimal, config-driven, cross-platform Claude Desktop MCP example — or, given we already expose MCP, a short doc/guide on pointing Claude Desktop at the existing server. Happy to help scope that down if you're up for it. Thanks again for the contribution! 🙌