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
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Server-side user configuration helpers."""
from __future__ import annotations
import json
from contextlib import asynccontextmanager
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, AsyncIterator, Callable, Optional, TypeVar
from openviking.core.namespace import canonical_user_root
from openviking.core.uri_validation import validate_content_target_uri
from openviking.server.config import AddTargetsConfig, UserConfig
from openviking.storage.acl import AclAction
from openviking_cli.exceptions import InvalidArgumentError, NotFoundError
if TYPE_CHECKING:
from openviking.server.config import ServerConfig
from openviking.server.identity import RequestContext
from openviking.storage.viking_fs import VikingFS
@dataclass(frozen=True)
class ResolvedAddTargets:
resource_uri: Optional[str] = None
skill_uri: Optional[str] = None
_UpdateResult = TypeVar("_UpdateResult")
def user_config_uri(ctx: RequestContext) -> str:
return f"{canonical_user_root(ctx)}/settings/user_config.json"
def user_config_backup_uri(ctx: RequestContext) -> str:
return f"{canonical_user_root(ctx)}/settings/user_config.backup.json"
@asynccontextmanager
async def _user_config_lock(
viking_fs: VikingFS,
uri: str,
ctx: RequestContext,
) -> AsyncIterator[Optional[dict[str, Any]]]:
uri_to_path = getattr(viking_fs, "_uri_to_path", None)
agfs = getattr(viking_fs, "_async_agfs", None)
acquire = getattr(agfs, "pathlock_acquire_exact", None)
release = getattr(agfs, "pathlock_release", None)
if not callable(uri_to_path) or not callable(acquire) or not callable(release):
yield None
return
path = uri_to_path(uri, ctx=ctx)
lease = await acquire(path)
try:
yield lease
finally:
await release(lease)
def _user_config_from_payload(payload: Any) -> UserConfig:
if not isinstance(payload, dict):
raise InvalidArgumentError("user config must be an object")
try:
return UserConfig.model_validate(payload)
except Exception as exc:
raise InvalidArgumentError(str(exc)) from exc
def validate_user_memory_policy(memory_policy: Optional[dict[str, Any]]) -> None:
if memory_policy is None:
return
from openviking.session.memory.memory_type_registry import get_default_registry
from openviking.session.memory_policy import MemoryPolicy
MemoryPolicy.from_dict(memory_policy).validate_memory_types(
set(get_default_registry().list_names(include_disabled=False))
)
async def validate_resource_add_target(
uri: str,
*,
ctx: RequestContext,
viking_fs: VikingFS,
) -> str:
resolved = validate_content_target_uri(
uri,
ctx,
kind="resource",
field_name="resource_uri",
)
await viking_fs._ensure_access(resolved, ctx, action=AclAction.WRITE)
return resolved
async def validate_skill_add_target(
uri: str,
*,
ctx: RequestContext,
viking_fs: VikingFS,
) -> str:
resolved = validate_content_target_uri(
uri,
ctx,
kind="skill",
field_name="skill_uri",
)
await viking_fs._ensure_access(resolved, ctx, action=AclAction.WRITE)
return resolved
async def validate_add_targets(
settings: AddTargetsConfig,
*,
ctx: RequestContext,
viking_fs: VikingFS,
) -> ResolvedAddTargets:
resource_uri = (
await validate_resource_add_target(settings.resource_uri, ctx=ctx, viking_fs=viking_fs)
if settings.resource_uri
else None
)
skill_uri = (
await validate_skill_add_target(settings.skill_uri, ctx=ctx, viking_fs=viking_fs)
if settings.skill_uri
else None
)
return ResolvedAddTargets(
resource_uri=resource_uri,
skill_uri=skill_uri,
)
async def read_user_config(
viking_fs: VikingFS,
ctx: RequestContext,
) -> UserConfig:
read_file = getattr(viking_fs, "read_file", None)
if not callable(read_file):
return UserConfig()
uri = user_config_uri(ctx)
try:
raw = await read_file(uri, ctx=ctx)
except (NotFoundError, FileNotFoundError):
return UserConfig()
try:
payload = json.loads(raw)
except json.JSONDecodeError as exc:
raise InvalidArgumentError(f"Invalid user config JSON: {exc}") from exc
return _user_config_from_payload(payload)
async def update_user_config(
viking_fs: VikingFS,
ctx: RequestContext,
updater: Callable[[UserConfig], _UpdateResult],
) -> _UpdateResult:
"""Apply a locked read-modify-write update to the current user's config."""
uri = user_config_uri(ctx)
async with _user_config_lock(viking_fs, uri, ctx) as handle:
current = await read_user_config(viking_fs, ctx)
before = current.model_dump(by_alias=True)
result = updater(current)
runtime = await validate_add_targets(current.add_targets, ctx=ctx, viking_fs=viking_fs)
current.add_targets.resource_uri = runtime.resource_uri
current.add_targets.skill_uri = runtime.skill_uri
validate_user_memory_policy(current.memory_policy)
if current.model_dump(by_alias=True) != before:
await _prepare_ttl_change(ctx, UserConfig.model_validate(before), current)
before_content = json.dumps(before, ensure_ascii=False, sort_keys=True)
await viking_fs.write_file(
user_config_backup_uri(ctx),
before_content,
ctx=ctx,
)
try:
await viking_fs.write_file(
uri,
json.dumps(
current.model_dump(by_alias=True, exclude_none=True),
ensure_ascii=False,
sort_keys=True,
),
ctx=ctx,
lease_ref=handle,
)
except Exception:
await viking_fs.write_file(
uri,
before_content,
ctx=ctx,
lease_ref=handle,
)
raise
if before.get("ttl") != current.model_dump(by_alias=True).get("ttl"):
await _publish_ttl_change(ctx, current)
return result
async def _prepare_ttl_change(ctx: RequestContext, before: UserConfig, after: UserConfig) -> None:
if before.ttl == after.ttl:
return
from openviking.ttl.wiring import get_ttl_adapter, ttl_config_supported
from openviking_cli.exceptions import UnimplementedError
if not ttl_config_supported():
raise UnimplementedError("Redis-backed TTL is not enabled in this deployment.")
await get_ttl_adapter().prepare_user_configuration(ctx, before.ttl, after.ttl)
async def _publish_ttl_change(ctx: RequestContext, config: UserConfig) -> None:
from openviking.ttl.wiring import get_ttl_adapter
adapter = get_ttl_adapter()
if adapter is not None:
await adapter.publish_user_configuration(ctx, config.ttl)
async def patch_user_config(viking_fs: VikingFS, ctx: RequestContext, patch: dict) -> UserConfig:
"""Apply a sparse settings patch through the existing locked write lifecycle."""
from openviking.config.merge import apply_three_state_patch
def update(current: UserConfig) -> UserConfig:
payload = current.model_dump(by_alias=True, exclude_none=True)
if "ttl" in patch:
payload = apply_three_state_patch(payload, {"ttl": patch["ttl"]})
if "memory_policy" in patch:
# Keep the existing whole-policy replacement semantics.
payload["memory_policy"] = patch["memory_policy"]
candidate = _user_config_from_payload(payload)
current.memory_policy = candidate.memory_policy
current.ttl = candidate.ttl
return current
return await update_user_config(viking_fs, ctx, update)
async def write_user_config(
viking_fs: VikingFS,
ctx: RequestContext,
user_config: UserConfig,
) -> ResolvedAddTargets:
runtime = await validate_add_targets(user_config.add_targets, ctx=ctx, viking_fs=viking_fs)
user_config.add_targets.resource_uri = runtime.resource_uri
user_config.add_targets.skill_uri = runtime.skill_uri
validate_user_memory_policy(user_config.memory_policy)
uri = user_config_uri(ctx)
async with _user_config_lock(viking_fs, uri, ctx) as handle:
await _prepare_ttl_change(ctx, UserConfig(), user_config)
await viking_fs.write_file(
uri,
json.dumps(
user_config.model_dump(by_alias=True, exclude_none=True),
ensure_ascii=False,
sort_keys=True,
),
ctx=ctx,
lease_ref=handle,
)
await _publish_ttl_change(ctx, user_config)
return runtime
async def delete_user_config(viking_fs: VikingFS, ctx: RequestContext) -> None:
try:
await viking_fs.rm(user_config_uri(ctx), ctx=ctx)
except (NotFoundError, FileNotFoundError):
pass
await _publish_ttl_change(ctx, UserConfig())
async def read_user_add_targets(
viking_fs: VikingFS,
ctx: RequestContext,
) -> AddTargetsConfig:
return (await read_user_config(viking_fs, ctx)).add_targets
async def write_user_add_targets(
viking_fs: VikingFS,
ctx: RequestContext,
settings: AddTargetsConfig,
) -> ResolvedAddTargets:
runtime = await validate_add_targets(settings, ctx=ctx, viking_fs=viking_fs)
def _set(user_config: UserConfig) -> None:
user_config.add_targets = settings
await update_user_config(viking_fs, ctx, _set)
return runtime
async def delete_user_add_targets(viking_fs: VikingFS, ctx: RequestContext) -> None:
def _clear(user_config: UserConfig) -> None:
user_config.add_targets = AddTargetsConfig()
await update_user_config(viking_fs, ctx, _clear)
async def read_user_memory_policy(
viking_fs: VikingFS,
ctx: RequestContext,
) -> Optional[dict[str, Any]]:
return (await read_user_config(viking_fs, ctx)).memory_policy
async def write_user_memory_policy(
viking_fs: VikingFS,
ctx: RequestContext,
memory_policy: Optional[dict[str, Any]],
) -> Optional[dict[str, Any]]:
normalized = UserConfig(memory_policy=memory_policy).memory_policy
validate_user_memory_policy(normalized)
def _set(user_config: UserConfig) -> None:
user_config.memory_policy = normalized
await update_user_config(viking_fs, ctx, _set)
return normalized
async def effective_resource_add_target(
*,
viking_fs: VikingFS,
ctx: RequestContext,
server_config: Optional[ServerConfig],
) -> Optional[str]:
user_settings = await read_user_add_targets(viking_fs, ctx)
if user_settings.resource_uri:
return await validate_resource_add_target(
user_settings.resource_uri, ctx=ctx, viking_fs=viking_fs
)
configured = getattr(
getattr(getattr(server_config, "user_config_defaults", None), "add_targets", None),
"resource_uri",
None,
)
if configured:
return await validate_resource_add_target(configured, ctx=ctx, viking_fs=viking_fs)
return None
async def effective_skill_add_target(
*,
viking_fs: VikingFS,
ctx: RequestContext,
server_config: Optional[ServerConfig],
) -> Optional[str]:
user_settings = await read_user_add_targets(viking_fs, ctx)
if user_settings.skill_uri:
return await validate_skill_add_target(
user_settings.skill_uri, ctx=ctx, viking_fs=viking_fs
)
configured = getattr(
getattr(getattr(server_config, "user_config_defaults", None), "add_targets", None),
"skill_uri",
None,
)
if configured:
return await validate_skill_add_target(configured, ctx=ctx, viking_fs=viking_fs)
return None
def public_add_targets(settings: AddTargetsConfig) -> dict[str, Optional[str]]:
return {
"resource_uri": settings.resource_uri,
"skill_uri": settings.skill_uri,
}