Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

4.9 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Memory extraction policy for session commits."""

from __future__ import annotations

import warnings
from dataclasses import dataclass
from typing import Any, Optional

from openviking.session.memory.constants import (
    AGENT_EVOLUTION_MEMORY_TYPES,
    EXPERIENCE_MEMORY_TYPE,
)
from openviking_cli.exceptions import InvalidArgumentError

_POLICY_KEYS = {"self", "peer", "memory_types", "working_memory"}
_TARGET_KEYS = {"enabled"}
_TRUE_STRINGS = {"1", "true", "yes", "on"}
_FALSE_STRINGS = {"", "0", "false", "no", "off"}


def _memory_policy_shape_error(key: str) -> str:
    if key == "working_memory":
        return "memory_policy.working_memory must be an object"
    return "memory_policy target must be an object"


def _memory_policy_keys_error(key: str) -> str:
    if key == "working_memory":
        return "memory_policy.working_memory supports only: enabled"
    return "memory_policy target supports only: enabled"


def _parse_enabled(value: Any, *, key: str) -> bool:
    if isinstance(value, bool):
        return value

    warnings.warn(
        f"memory_policy.{key}.enabled should be a boolean; legacy coercion is deprecated",
        FutureWarning,
        stacklevel=3,
    )
    if isinstance(value, str):
        normalized = value.strip().casefold()
        if normalized in _TRUE_STRINGS:
            return True
        if normalized in _FALSE_STRINGS:
            return False

    # Preserve the permissive pre-v0.5 behavior for uncommon legacy values.
    # This avoids breaking persisted policy dictionaries while callers migrate
    # to genuine JSON booleans.
    return bool(value)


def _target_enabled(data: Any, *, default_enabled: bool, key: str = "target") -> bool:
    if data is None:
        return default_enabled
    if not isinstance(data, dict):
        raise InvalidArgumentError(_memory_policy_shape_error(key))
    extra_keys = set(data) - _TARGET_KEYS
    if extra_keys:
        raise InvalidArgumentError(_memory_policy_keys_error(key))
    if "enabled" not in data:
        return default_enabled
    return _parse_enabled(data["enabled"], key=key)


def _parse_memory_types(data: Any) -> Optional[set[str]]:
    if data is None:
        return None
    if not isinstance(data, list):
        raise InvalidArgumentError("memory_policy.memory_types must be a list")
    memory_types = set()
    for item in data:
        if not isinstance(item, str) or not item:
            raise InvalidArgumentError("memory_policy.memory_types must contain non-empty strings")
        memory_types.add(item)
    if EXPERIENCE_MEMORY_TYPE in memory_types:
        memory_types.update(AGENT_EVOLUTION_MEMORY_TYPES)
    else:
        memory_types.difference_update(AGENT_EVOLUTION_MEMORY_TYPES)
    return memory_types


@dataclass
class MemoryPolicy:
    """Effective memory policy for one commit."""

    self_enabled: bool = True
    peer_enabled: bool = True
    memory_types: Optional[set[str]] = None
    enable_working_memory: bool = False

    @classmethod
    def default(cls) -> "MemoryPolicy":
        return cls()

    @classmethod
    def from_dict(cls, data: Any) -> "MemoryPolicy":
        if data is None:
            return cls.default()
        if isinstance(data, MemoryPolicy):
            return data
        if not isinstance(data, dict):
            raise InvalidArgumentError("memory_policy must be an object")
        extra_keys = set(data) - _POLICY_KEYS
        if extra_keys:
            raise InvalidArgumentError(
                "memory_policy supports only: " + ", ".join(sorted(_POLICY_KEYS))
            )
        return cls(
            self_enabled=_target_enabled(data.get("self"), default_enabled=True, key="self"),
            peer_enabled=_target_enabled(data.get("peer"), default_enabled=True, key="peer"),
            memory_types=_parse_memory_types(data.get("memory_types")),
            enable_working_memory=_target_enabled(
                data.get("working_memory"), default_enabled=False, key="working_memory"
            ),
        )

    def validate_memory_types(self, known_memory_types: set[str]) -> None:
        if self.memory_types is None:
            return
        unknown = self.memory_types - known_memory_types
        if unknown:
            raise InvalidArgumentError(
                "Unknown memory_policy.memory_types: " + ", ".join(sorted(unknown))
            )

    def to_dict(self) -> dict[str, Any]:
        data: dict[str, Any] = {
            "self": {"enabled": self.self_enabled},
            "peer": {"enabled": self.peer_enabled},
        }
        # Queue and recovery snapshots must preserve explicit opt-in across
        # default changes, as must persisted user and session policies.
        data["working_memory"] = {"enabled": self.enable_working_memory}
        if self.memory_types is not None:
            data["memory_types"] = sorted(self.memory_types)
        return data