Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(mcp): add early detection for multi-instance stdio contention (#611)
Matt Van Horne56e245e1bc9
diff --git a/openviking/service/core.py b/openviking/service/core.pyindex 5764fed1e..11f20037c 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -214,6 +214,12 @@ class OpenVikingService:logger.debug("Already initialized")return+ # Acquire advisory lock on data directory to prevent multi-process+ # contention (see https://github.com/volcengine/OpenViking/issues/473).+ from openviking.utils.process_lock import acquire_data_dir_lock++ acquire_data_dir_lock(self._config.storage.workspace)+if self._vikingdb_manager is None:self._init_storage(self._config.storage,diff --git a/openviking/utils/process_lock.py b/openviking/utils/process_lock.pynew file mode 100644index 000000000..854f624f7--- /dev/null+++ b/openviking/utils/process_lock.py@@ -0,0 +1,102 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: Apache-2.0+"""PID-based advisory lock for data directory exclusivity.++Prevents multiple OpenViking processes from contending for the same data+directory, which causes silent failures in AGFS and VectorDB.+"""++import atexit+import os+import signal++from openviking_cli.utils import get_logger++logger = get_logger(__name__)++LOCK_FILENAME = ".openviking.pid"+++class DataDirectoryLocked(RuntimeError):+ """Raised when another OpenViking process holds the data directory lock."""+++def _read_pid_file(lock_path: str) -> int:+ """Read PID from lock file. Returns 0 if unreadable."""+ try:+ with open(lock_path) as f:+ return int(f.read().strip())+ except (OSError, ValueError):+ return 0+++def _is_pid_alive(pid: int) -> bool:+ """Check whether a process with the given PID is still running."""+ if pid <= 0:+ return False+ try:+ os.kill(pid, 0)+ return True+ except ProcessLookupError:+ return False+ except PermissionError:+ # Process exists but we can't signal it.+ return True+++def acquire_data_dir_lock(data_dir: str) -> str:+ """Acquire an advisory PID lock on *data_dir*.++ Returns the path to the lock file on success.++ Raises ``DataDirectoryLocked`` if another live process already holds the+ lock, with a message that explains the situation and suggests HTTP mode.+ """+ lock_path = os.path.join(data_dir, LOCK_FILENAME)+ my_pid = os.getpid()++ existing_pid = _read_pid_file(lock_path)+ if existing_pid and existing_pid != my_pid and _is_pid_alive(existing_pid):+ raise DataDirectoryLocked(+ f"Another OpenViking process (PID {existing_pid}) is already using "+ f"the data directory '{data_dir}'. Running multiple OpenViking "+ f"instances on the same data directory causes silent storage "+ f"contention and data corruption.\n\n"+ f"To fix this, use one of these approaches:\n"+ f" 1. Use HTTP mode: start a single openviking-server and connect "+ f"via --transport http (recommended for multi-session hosts)\n"+ f" 2. Use separate data directories for each instance\n"+ f" 3. Stop the other process (PID {existing_pid}) first"+ )++ # Write our PID (overwrites stale lock from a dead process).+ try:+ os.makedirs(data_dir, exist_ok=True)+ with open(lock_path, "w") as f:+ f.write(str(my_pid))+ except OSError as exc:+ logger.warning("Could not write PID lock %s: %s", lock_path, exc)+ return lock_path++ # Schedule cleanup on exit.+ def _cleanup(*_args: object) -> None:+ try:+ if os.path.isfile(lock_path):+ stored = _read_pid_file(lock_path)+ if stored == my_pid:+ os.remove(lock_path)+ except OSError:+ pass++ atexit.register(_cleanup)+ # Also try to clean up on SIGTERM (graceful shutdown).+ try:+ signal.signal(+ signal.SIGTERM, lambda sig, frame: (_cleanup(), signal.default_int_handler(sig, frame))+ )+ except (OSError, ValueError):+ # signal.signal() can fail in non-main threads.+ pass++ logger.debug("Acquired data directory lock: %s (PID %d)", lock_path, my_pid)+ return lock_pathdiff --git a/tests/misc/test_process_lock.py b/tests/misc/test_process_lock.pynew file mode 100644index 000000000..458465931--- /dev/null+++ b/tests/misc/test_process_lock.py@@ -0,0 +1,61 @@+"""Tests for PID-based advisory lock on data directories."""++import os+import tempfile++from openviking.utils.process_lock import (+ LOCK_FILENAME,+ DataDirectoryLocked,+ acquire_data_dir_lock,+)+++class TestProcessLock:+ def test_acquires_lock_on_empty_dir(self):+ with tempfile.TemporaryDirectory() as tmpdir:+ lock_path = acquire_data_dir_lock(tmpdir)+ assert os.path.isfile(lock_path)+ with open(lock_path) as f:+ assert int(f.read().strip()) == os.getpid()++ def test_same_pid_can_reacquire(self):+ with tempfile.TemporaryDirectory() as tmpdir:+ acquire_data_dir_lock(tmpdir)+ # Should not raise when same process re-acquires.+ acquire_data_dir_lock(tmpdir)++ def test_stale_lock_is_replaced(self):+ with tempfile.TemporaryDirectory() as tmpdir:+ lock_path = os.path.join(tmpdir, LOCK_FILENAME)+ # Write a PID that does not exist (very high number).+ with open(lock_path, "w") as f:+ f.write("999999999")+ # Should succeed because the PID is dead.+ acquire_data_dir_lock(tmpdir)+ with open(lock_path) as f:+ assert int(f.read().strip()) == os.getpid()++ def test_live_pid_blocks_acquisition(self):+ with tempfile.TemporaryDirectory() as tmpdir:+ lock_path = os.path.join(tmpdir, LOCK_FILENAME)+ # PID 1 (init/launchd) is always alive.+ with open(lock_path, "w") as f:+ f.write("1")+ try:+ acquire_data_dir_lock(tmpdir)+ raise AssertionError("Should have raised DataDirectoryLocked")+ except DataDirectoryLocked as exc:+ assert "PID 1" in str(exc)+ assert "HTTP mode" in str(exc)++ def test_error_message_includes_remediation(self):+ with tempfile.TemporaryDirectory() as tmpdir:+ lock_path = os.path.join(tmpdir, LOCK_FILENAME)+ with open(lock_path, "w") as f:+ f.write("1")+ try:+ acquire_data_dir_lock(tmpdir)+ except DataDirectoryLocked as exc:+ msg = str(exc)+ assert "openviking-server" in msg+ assert "separate data directories" in msg