[Question]: 怎么才能验证构建成功了。

[DamonDay]

Your Question

大佬你好，我基于 OpenViking 在一个飞书 Bot 项目里集成了语义记忆功能，用了 Doubao embedding +
DeepSeek VLM + Stop Hook 架构。全程 vibe coding 摸索了一轮，15 个 commit
总算把基本链路跑通了，但说实话现在心里很虚——不知道怎样才算"构建成功"。

想请教几个核心问题：

---

1. 怎样验证记忆系统真正在工作？

目前我的验证手段只有：

• client.find(query=..., target_uri="viking://resources/") 能返回结果且 score > 0.4
• 索引脚本跑完没报错
• E2E 测试 ingest-stop → recall 能跑通

但我不确定：

• L0/L1 摘要是否生成成功？ auto_generate_l0=True, auto_generate_l1=True 配了，但怎么验证某个文件确实有 L0/L1
  被提取出来了？在哪里能看到？
• session.commit() 后的长期记忆提取是否成功？ 每 5 轮对话自动 commit，VLM 应该提取 6 类记忆（profile,
  preferences, entities, events, cases,
  patterns），但我不知道怎么确认提取确实发生了、提取质量如何。viking://user/memories/ 下应该有东西，但目前
  client.ls("viking://user/memories/") 返回空。

有没有一个"健康检查清单"？ 比如：索引 N 个文件后，应该在 viking:// 下看到哪些路径有数据？

---

2. AGFS 端口 1833 的单实例限制

实际遇到的问题：

• MCP server（通过 .mcp.json 启动）启动时占用 1833
• Stop Hook 调用 ov_memory.py 时也需要初始化 SyncOpenViking，又要启动 AGFS
• 两者互斥，导致 Stop Hook 在 MCP server 运行期间会失败
• 更麻烦的是进程退出后端口经常处于 CLOSE_WAIT 状态，需要手动 kill 孤儿进程

这个单实例限制是设计如此还是有解法？examples/claude-memory-plugin 里的方案是优先走 HTTP server，local 作为
fallback——这是推荐的生产用法吗？

---

3. 日志输出到 stdout 的问题

make_config() 里设了 log_level="WARNING"，但 SyncOpenViking 初始化时仍然有大量 INFO 级别日志输出到
stdout（AGFS 启动、collection 加载、transaction manager 等），和我的 JSON 输出混在一起，导致调用方解析失败。

我目前的 workaround 是用 grep '^{' | tail -1 过滤。有没有正确的方式抑制这些日志？

---

4. Candidate data is None 警告

从 Ollama bge-m3（1024维）迁移到 Doubao embedding（也是1024维）后，每次 find() 调用都会打出大量 Candidate
data is None for label index N 的 WARNING。我猜测是旧索引残留数据和新 embedding 空间不兼容，但：

• 这个警告的实际影响是什么？会影响搜索质量吗？
• 全量 re-index 后会消失吗？
• 正确的 embedding 迁移流程是什么？我目前的做法是直接删除 vectordb/ 目录然后重新跑
  index_kb.py，不知道是否遗漏了什么。

---

5. examples/claude-memory-plugin 和 MCP server 的关系

项目里有两种集成方式：

• MCP server（openviking_mcp_server.py）：通过 Claude Code 的 MCP 协议暴露 search/add_memory/ls 工具
• claude-memory-plugin（examples/claude-memory-plugin/）：通过 4 个 Hook + recall skill 实现完整生命周期

我目前是混合使用：MCP server 提供搜索能力 + Stop Hook 做对话捕获（参考了 plugin 的 ov_memory.py）。但不确定：

• 这两种方式是否打算共存？还是 plugin 会替代 MCP server？
• 对于飞书 Bot 这种"每条消息 spawn 一次 Claude CLI"的短进程场景，推荐哪种方式？

---

我的构建背景

Tech Stack:

• Embedding: Volcengine Doubao (doubao-embedding-vision-251215, 1024dim)
• VLM: DeepSeek v3.1 via enterprise proxy
• Storage: local (SyncOpenViking, AGFS on port 1833)
• Integration: Node.js 飞书 Bot → spawn Claude CLI → MCP server + Stop Hook

Done:

• 15 commits on memory/viking-v0 branch
• Embedding 从 Ollama bge-m3 迁移到 Doubao
• MCP tools 精简 5→3，Stop Hook 自动对话捕获
• 49 个 Python 单元测试 + 16 个 E2E 集成测试
• 单文件索引测试通过 (CLAUDE.md, search score=0.524)

Pain points:

• 不知道 L0/L1/L2 是否真的生成了
• AGFS 端口冲突和孤儿进程
• 日志污染 stdout
• embedding 迁移后大量 None candidate 警告
• session.commit() 后 viking://user/memories/ 为空

感谢！

Context

No response

Code Example (Optional)

Related Area

Installation / Setup

Before Asking

• I have checked the documentation

[DamonDay]

How to verify OpenViking is properly set up? (构建成功的验证标准)

Context

I'm integrating OpenViking into a Feishu (Lark) chat bot that spawns claude -p per message (short-lived process). The setup:

• Embedding: Volcengine Doubao (doubao-embedding-vision-251215, 1024-dim)
• VLM: DeepSeek v3.1 via OpenAI-compatible proxy
• Storage: local (SyncOpenViking, AGFS on port 1833)
• Integration: MCP server (search/add_memory/ls) + Claude Code Stop Hook (auto-capture conversations)

After 15 commits of vibe-coding, the basic pipeline works (indexing, search, ingest-stop, recall), but I'm unsure how to verify the system is truly healthy.

---

Question 1: How to verify L0/L1 generation and memory extraction?

Config

config = {
    "storage": {
        "agfs": {"backend": "local", "path": STORAGE_PATH},
        "vectordb": {
            "backend": "local",
            "path": STORAGE_PATH,
            "dimension": 1024,
            "distance_metric": "cosine",
        },
    },
    "embedding": {
        "dense": {
            "provider": "volcengine",
            "model": "doubao-embedding-vision-251215",
            "api_key": os.environ.get("EMBEDDING_API_KEY", ""),
            "api_base": "https://abcdefg.hijklmn.volces.com/api/v3",
            "dimension": 1024,
        },
    },
    "vlm": {
        "provider": "openai",
        "model": "deepseek-v3.1",
        "api_key": os.environ.get("VLM_API_KEY", ""),
        "api_base": "https://my-proxy.example.com/v1",
        "use_litellm": False,
    },
    "auto_generate_l0": True,
    "auto_generate_l1": True,
    "log_level": "WARNING",
}

What I can verify

from openviking import SyncOpenViking
from openviking_cli.utils.config import OpenVikingConfig, set_openviking_config

cfg = OpenVikingConfig.from_dict(config)
set_openviking_config(cfg)
client = SyncOpenViking(path=STORAGE_PATH)
client.initialize()

# Search works - returns results with scores
result = client.find(query="some query", target_uri="viking://resources/", limit=5)
# result.resources has items with .uri, .score, .abstract ✓

# ls works
items = client.ls("viking://resources/knowledge/")
# Returns directory listing ✓

client.close()

What I cannot verify

1. L0/L1 generation: auto_generate_l0=True is set, but how do I confirm L0/L1 abstracts were actually generated for indexed files? Where are they stored? Can I read them via client.read()?

2. Memory extraction after session.commit(): My Stop Hook accumulates conversation turns and calls session.commit() every 5 turns. I expect VLM to extract long-term memories to viking://user/memories/ and viking://agent/memories/. But:

items = client.ls("viking://user/memories/")
# Returns empty []

Is this expected if commit hasn't triggered yet, or is something misconfigured?

Is there a health-check checklist? For example: "after indexing N files, you should see data under these URIs..."

---

Question 2: AGFS port 1833 single-instance limitation

Problem

My architecture has two components that both need SyncOpenViking:

1. MCP server (long-running, started via .mcp.json by Claude CLI)
2. Stop Hook script (short-lived, runs after each Claude response)

Both initialize SyncOpenViking(path=...) which starts AGFS on port 1833. They conflict:

# MCP server is running, holding port 1833
# Stop Hook tries to start → AGFS fails to bind → hook fails silently

Additionally, when processes exit uncleanly, port 1833 stays in CLOSE_WAIT:

$ lsof -i :1833
python3  74259  CLOSE_WAIT
python3  76365  CLOSE_WAIT
# Must manually kill these before restarting

Questions

• Is the single-AGFS-instance-per-port limitation by design?
• For short-lived processes that need OpenViking access while an MCP server is running, what's the recommended approach?
• I noticed examples/claude-memory-plugin prefers HTTP mode with local fallback — is HTTP server the recommended production pattern?

---

Question 3: Logging goes to stdout despite log_level="WARNING"

Reproduction

config = {
    # ... same as above ...
    "log_level": "WARNING",
}

cfg = OpenVikingConfig.from_dict(config)
set_openviking_config(cfg)
client = SyncOpenViking(path=STORAGE_PATH)
client.initialize()

result = client.find(query="test", target_uri="viking://resources/", limit=3)
print(json.dumps({"score": result.resources[0].score}))  # My JSON output

client.close()

Actual output (stdout)

2026-02-25 19:24:13 - openviking.agfs_manager - INFO - [AGFSManager] Starting AGFS on port 1833
2026-02-25 19:24:13 - openviking.agfs_manager - INFO - [AGFSManager] AGFS is ready
2026-02-25 19:24:13 - openviking.storage.queuefs.queue_manager - INFO - [QueueManager] Initialized
2026-02-25 19:24:13 - openviking - INFO - Loading collection: context
2026-02-25 19:24:13 - openviking - INFO - Successfully loaded collection: context
2026-02-25 19:24:13 - openviking.service.core - INFO - Initialized embedder (dim 1024)
2026-02-25 19:24:13 - openviking - WARNING - Candidate data is None for label index 0
2026-02-25 19:24:13 - openviking - WARNING - Candidate data is None for label index 1
... (20+ more log lines)
{"score": 0.524}   ← my actual output, buried at the end

Expected

With log_level="WARNING", INFO logs should be suppressed. And ideally all logs should go to stderr, not stdout.

Current workaround

# Filter JSON from mixed output
bridge_output=$(python3 my_script.py 2>/dev/null | grep '^{' | tail -1)

---

Question 4: "Candidate data is None" warnings after embedding migration

Context

Migrated from Ollama bge-m3 (1024-dim) to Volcengine Doubao (also 1024-dim). Migration steps:

# 1. Backup old index
cp -r ~/.openviking/myproject ~/.openviking/myproject_backup_bge_m3

# 2. Clear vectordb
rm -rf ~/.openviking/myproject/vectordb/

# 3. Re-index with new embedding
python3 scripts/openviking_index_kb.py

Warnings after migration

Every find() call produces warnings:

WARNING - Candidate data is None for label index 0 (label: 5141167635354807936), skipping.
WARNING - Candidate data is None for label index 1 (label: 8701055873261240864), skipping.
WARNING - Candidate data is None for label index 0 (label: 12143898875921835331), skipping.
... (10+ warnings per query)

Questions

• What do these warnings mean? Do they affect search quality?
• Will they disappear after a full re-index of all knowledge base files? (I've only indexed 1 file so far)
• Is my migration approach correct (delete vectordb + re-index), or is there a better migration path?

---

Question 5: claude-memory-plugin vs MCP server — recommended pattern?

I found two integration patterns in the project:

Pattern	Implementation	Memory retrieval	Session lifecycle
MCP server	mcp.server.fastmcp + search/add_memory/ls tools	Claude calls openviking_search inline	Manual (no start/end hooks)
claude-memory-plugin	4 hooks (SessionStart/Stop/End) + recall skill	memory-recall skill (fork subagent)	Full lifecycle (create → ingest → commit)

I'm currently using a hybrid: MCP server for inline search + Stop Hook for auto-capture (adapted from the plugin's ov_memory.py).

For a "per-message spawn" scenario (Feishu bot spawns claude -p per message, short-lived process):

• Which pattern is recommended?
• Will the plugin approach replace the MCP server approach, or are they intended to coexist?

---

Environment

OpenViking: (installed from source, with 4 patches on venv)
Python: 3.13
OS: macOS 14.3 (Apple Silicon)
Claude Code: latest

Thanks for the amazing project! Just need help calibrating what "working correctly" looks like.

[kkkwjx07]

1. 通常你可以本地的path路径下看到对应的agfs文件目录
2. 建议用server模式，通过cli接入
3. 日志配置参数有调整，可以看看是否升级到最新版本
4. 目前还不支持embedding迁移，只能删了重建

[kweinoces-ctrl]

查看评论

[baojun-zhang]

对于 "AGFS 端口冲突和孤儿进程" 问题
已支持 AGFS binding client 模式 #304
使用方式可参考https://github.com/volcengine/OpenViking/blob/main/docs/zh/guides/01-configuration.md

{
  "storage": {
    "agfs": {
      "mode": "binding-client",
      "backend": "local"
    }
  }
}