feat(memory): add Claude-style memory runtime (HKUDS#267)

* Add Claude-style memory runtime

* fix(memory): trim relevance EOF whitespace

Author: tjb-tech

src/openharness/commands/registry.py

@@ -4,6 +4,7 @@
 
 import importlib.metadata
 import json
+import os
 import re
 import shutil
 import subprocess
@@ -38,8 +39,28 @@
     list_memory_files,
     migrate_memory,
     remove_memory_entry,
+    scan_memory_files,
+)
+from openharness.memory.agent import (
+    ensure_agent_memory_vault,
+    get_agent_memory_entrypoint,
+    initialize_agent_memory_from_snapshot,
+)
+from openharness.memory.schema import (
+    DEFAULT_MEMORY_SCOPE,
+    DEFAULT_MEMORY_TYPE,
+    MEMORY_TYPES,
+    is_disabled_metadata,
+    is_memory_expired,
+    parse_memory_scope,
+    parse_memory_type,
+    split_memory_file,
+)
+from openharness.memory.team import (
+    check_team_memory_secrets,
+    ensure_team_memory_vault,
+    get_team_memory_dir,
 )
-from openharness.memory.schema import is_disabled_metadata, is_memory_expired, split_memory_file
 from openharness.output_styles import load_output_styles
 from openharness.permissions import PermissionChecker, PermissionMode
 from openharness.plugins import load_plugins
@@ -60,6 +81,12 @@
     restore_memory_backup,
     start_dream_now,
 )
+from openharness.services.memory_extract import extract_memories_from_turn
+from openharness.services.session_memory import (
+    get_session_memory_content,
+    get_session_memory_path,
+    update_session_memory_file,
+)
 from openharness.services.session_backend import DEFAULT_SESSION_BACKEND, SessionBackend
 from openharness.skills import load_skill_registry
 from openharness.skills.types import SkillDefinition
@@ -654,7 +681,10 @@ async def _memory_handler(args: str, context: CommandContext) -> CommandResult:
                 message=(
                     f"Memory store: {backend.label}\n"
                     f"Memory directory: {backend.get_memory_dir()}\n"
-                    f"Entrypoint: {backend.get_entrypoint()}"
+                    f"Entrypoint: {backend.get_entrypoint()}\n"
+                    "Commands: list, show NAME, add TITLE :: CONTENT, remove NAME, "
+                    "edit [NAME], validate, extract, session, team, agent, "
+                    "migrate --dry-run, migrate --apply"
                 )
             )
         action = tokens[0]
@@ -710,19 +740,55 @@ async def _memory_handler(args: str, context: CommandContext) -> CommandResult:
                 return CommandResult(message=f"Memory entry not found: {rest}")
             return CommandResult(message=content)
         if action == "add" and rest:
-            title, separator, content = rest.partition("::")
+            memory_type, scope, cleaned_rest = _parse_memory_add_flags(rest)
+            title, separator, content = cleaned_rest.partition("::")
             if not separator or not title.strip() or not content.strip():
-                return CommandResult(message="Usage: /memory add TITLE :: CONTENT")
-            path = backend.add_entry(title.strip(), content.strip())
+                return CommandResult(message="Usage: /memory add [--type TYPE] [--scope SCOPE] TITLE :: CONTENT")
+            if context.memory_backend is None:
+                path = add_memory_entry(
+                    context.cwd,
+                    title.strip(),
+                    content.strip(),
+                    memory_type=memory_type,
+                    scope=scope,
+                )
+            else:
+                path = backend.add_entry(title.strip(), content.strip())
             return CommandResult(message=f"Added memory entry {path.name}")
         if action == "remove" and rest:
             if backend.remove_entry(rest.strip()):
                 return CommandResult(message=f"Removed memory entry {rest.strip()}")
             return CommandResult(message=f"Memory entry not found: {rest.strip()}")
+        if action == "edit":
+            return _handle_memory_edit_command(rest, context, backend)
+        if action == "validate":
+            return _handle_memory_validate_command(context)
+        if action == "extract":
+            if context.memory_backend is not None:
+                return CommandResult(message="Memory extraction is only supported for OpenHarness project memory.")
+            result = await extract_memories_from_turn(
+                cwd=context.cwd,
+                api_client=context.engine.api_client,
+                model=context.engine.model,
+                messages=context.engine.messages,
+                max_records=load_settings().memory.auto_extract_max_records,
+            )
+            if result.skipped:
+                return CommandResult(message=f"Memory extraction skipped: {result.reason}")
+            return CommandResult(
+                message="Memory extraction wrote:\n" + "\n".join(f"- {path}" for path in result.written_paths)
+            )
+        if action == "session":
+            return _handle_memory_session_command(rest, context)
+        if action == "team":
+            return _handle_memory_team_command(rest, context)
+        if action == "agent":
+            return _handle_memory_agent_command(rest, context)
         return CommandResult(
             message=(
                 "Usage: /memory "
-                "[list|show NAME|add TITLE :: CONTENT|remove NAME|"
+                "[list|show NAME|add TITLE :: CONTENT|remove NAME|edit [NAME]|"
+                "validate|extract|session|team|agent|"
                 "migrate --dry-run|migrate --apply]"
             )
         )
@@ -2478,6 +2544,158 @@ async def _plugin_command_handler(
     return registry
 
 
+def _handle_memory_edit_command(
+    args: str,
+    context: CommandContext,
+    backend: MemoryCommandBackend,
+) -> CommandResult:
+    memory_dir = backend.get_memory_dir()
+    target = backend.get_entrypoint()
+    if args.strip():
+        path, invalid = _resolve_memory_entry_path(memory_dir, args.strip())
+        if invalid:
+            return CommandResult(message="Memory entry path must stay within the configured memory directory.")
+        if path is None:
+            return CommandResult(message=f"Memory entry not found: {args.strip()}")
+        target = path
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.touch(exist_ok=True)
+    editor = os.environ.get("VISUAL") or os.environ.get("EDITOR")
+    if not editor:
+        return CommandResult(message=f"Memory file ready: {target}\nSet $VISUAL or $EDITOR to open it from /memory edit.")
+    result = subprocess.run([editor, str(target)], cwd=context.cwd, check=False)
+    if result.returncode != 0:
+        return CommandResult(message=f"Editor exited with status {result.returncode}: {editor}")
+    return CommandResult(message=f"Edited memory file: {target}")
+
+
+def _parse_memory_add_flags(args: str):
+    """Parse optional ``/memory add`` type/scope flags."""
+
+    memory_type = DEFAULT_MEMORY_TYPE
+    scope = DEFAULT_MEMORY_SCOPE
+    rest = args.strip()
+    changed = True
+    while changed:
+        changed = False
+        if rest.startswith("--type "):
+            _, _, tail = rest.partition(" ")
+            raw, _, rest = tail.partition(" ")
+            parsed = parse_memory_type(raw, default=DEFAULT_MEMORY_TYPE)
+            if parsed is not None:
+                memory_type = parsed
+            changed = True
+        if rest.startswith("--scope "):
+            _, _, tail = rest.partition(" ")
+            raw, _, rest = tail.partition(" ")
+            parsed_scope = parse_memory_scope(raw, default=DEFAULT_MEMORY_SCOPE)
+            if parsed_scope is not None:
+                scope = parsed_scope
+            changed = True
+    return memory_type, scope, rest
+
+
+def _handle_memory_validate_command(context: CommandContext) -> CommandResult:
+    memory_dir = get_project_memory_dir(context.cwd)
+    headers = scan_memory_files(context.cwd, max_files=500)
+    issues: list[str] = []
+    for header in headers:
+        raw_type = header.frontmatter.get("type") or header.frontmatter.get("memory_type")
+        if parse_memory_type(raw_type) is None:
+            issues.append(
+                f"- {header.relative_path}: invalid or missing type {raw_type!r}; expected {', '.join(MEMORY_TYPES)}"
+            )
+        if "team" in Path(header.relative_path).parts:
+            try:
+                text = header.path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                text = ""
+            secret_error = check_team_memory_secrets(text)
+            if secret_error:
+                issues.append(f"- {header.relative_path}: {secret_error}")
+    if not issues:
+        return CommandResult(
+            message=(
+                "Memory validation passed.\n"
+                f"- files: {len(headers)}\n"
+                f"- memory_dir: {memory_dir}"
+            )
+        )
+    return CommandResult(message="Memory validation issues:\n" + "\n".join(issues))
+
+
+def _handle_memory_session_command(args: str, context: CommandContext) -> CommandResult:
+    action = args.split(maxsplit=1)[0] if args.strip() else "status"
+    path = get_session_memory_path(context.cwd, context.session_id or "default")
+    if action == "update":
+        path = update_session_memory_file(
+            context.cwd,
+            context.engine.messages,
+            tool_metadata=context.engine.tool_metadata,
+            session_id=context.session_id or "default",
+        )
+        return CommandResult(message=f"Updated session memory: {path}")
+    if action == "show":
+        content = get_session_memory_content(path)
+        return CommandResult(message=content or f"No session memory at {path}")
+    return CommandResult(
+        message=(
+            "Session memory:\n"
+            f"- path: {path}\n"
+            f"- exists: {path.exists()}\n"
+            "Commands: /memory session [status|show|update]"
+        )
+    )
+
+
+def _handle_memory_team_command(args: str, context: CommandContext) -> CommandResult:
+    action = args.split(maxsplit=1)[0] if args.strip() else "status"
+    team_dir = ensure_team_memory_vault(context.cwd)
+    if action == "list":
+        files = sorted(path for path in team_dir.rglob("*.md") if path.name != "MEMORY.md")
+        return CommandResult(message="\n".join(str(path.relative_to(team_dir)) for path in files) or "No team memory files.")
+    if action == "validate":
+        issues: list[str] = []
+        for path in sorted(team_dir.rglob("*.md")):
+            if path.name == "MEMORY.md":
+                continue
+            text = path.read_text(encoding="utf-8", errors="replace")
+            secret_error = check_team_memory_secrets(text)
+            if secret_error:
+                issues.append(f"- {path.relative_to(team_dir)}: {secret_error}")
+        return CommandResult(message="Team memory validation passed." if not issues else "\n".join(issues))
+    return CommandResult(
+        message=(
+            "Team memory:\n"
+            f"- directory: {get_team_memory_dir(context.cwd)}\n"
+            f"- exists: {team_dir.exists()}\n"
+            "Commands: /memory team [status|list|validate]"
+        )
+    )
+
+
+def _handle_memory_agent_command(args: str, context: CommandContext) -> CommandResult:
+    parts = args.split()
+    action = parts[0] if parts else "status"
+    agent_type = parts[1] if len(parts) > 1 else "default"
+    scope = parts[2] if len(parts) > 2 else "project"
+    if scope not in {"user", "project", "local"}:
+        return CommandResult(message="Agent memory scope must be one of: user, project, local")
+    if action == "snapshot":
+        target = initialize_agent_memory_from_snapshot(context.cwd, agent_type, scope)  # type: ignore[arg-type]
+        return CommandResult(message=f"Initialized agent memory from snapshot: {target}" if target else "No snapshot found.")
+    vault = ensure_agent_memory_vault(context.cwd, agent_type, scope)  # type: ignore[arg-type]
+    return CommandResult(
+        message=(
+            "Agent memory:\n"
+            f"- agent_type: {agent_type}\n"
+            f"- scope: {scope}\n"
+            f"- directory: {vault}\n"
+            f"- entrypoint: {get_agent_memory_entrypoint(context.cwd, agent_type, scope)}"
+        )
+    )
+
+
 def _resolve_memory_entry_path(memory_dir: Path, candidate: str) -> tuple[Path | None, bool]:
     """Resolve a memory entry path while enforcing containment under ``memory_dir``."""
 

src/openharness/config/settings.py

@@ -63,8 +63,12 @@ class MemorySettings(BaseModel):
     enabled: bool = True
     max_files: int = 5
     max_entrypoint_lines: int = 200
+    max_entrypoint_bytes: int = 25_000
     context_window_tokens: int | None = None
     auto_compact_threshold_tokens: int | None = None
+    auto_extract_enabled: bool = False
+    auto_extract_max_records: int = 3
+    session_memory_enabled: bool = True
     auto_dream_enabled: bool = False
     auto_dream_min_hours: float = 24.0
     auto_dream_min_sessions: int = 5

src/openharness/engine/query_engine.py

@@ -152,6 +152,63 @@ def _schedule_auto_dream(self) -> None:
             **kwargs,
         )
 
+    def _prepare_session_memory(self) -> None:
+        """Expose file-backed session memory to compaction when enabled."""
+
+        if self._settings is None or not self._settings.memory.session_memory_enabled:
+            return
+        if not self._settings.memory.enabled:
+            return
+        from openharness.services.session_memory import prepare_session_memory_metadata
+
+        prepare_session_memory_metadata(
+            self._cwd,
+            self._tool_metadata,
+            session_id=str(self._tool_metadata.get("session_id") or "default"),
+        )
+
+    async def _update_session_memory(self) -> None:
+        """Persist a session checkpoint after a user turn."""
+
+        if self._settings is None or not self._settings.memory.session_memory_enabled:
+            return
+        if not self._settings.memory.enabled:
+            return
+        from openharness.services.session_memory import update_session_memory_file
+
+        update_session_memory_file(
+            self._cwd,
+            list(self._messages),
+            tool_metadata=self._tool_metadata,
+            session_id=str(self._tool_metadata.get("session_id") or "default"),
+        )
+
+    async def _extract_durable_memories(self) -> None:
+        """Run the optional durable memory extraction pass."""
+
+        if self._settings is None or not self._settings.memory.auto_extract_enabled:
+            return
+        if not self._settings.memory.enabled:
+            return
+        from openharness.services.memory_extract import extract_memories_from_turn
+
+        try:
+            result = await extract_memories_from_turn(
+                cwd=self._cwd,
+                api_client=self._api_client,
+                model=self._model,
+                messages=list(self._messages),
+                max_records=self._settings.memory.auto_extract_max_records,
+            )
+        except Exception as exc:
+            self._tool_metadata["memory_extract_last_error"] = str(exc)
+            return
+        self._tool_metadata["memory_extract_last"] = {
+            "skipped": result.skipped,
+            "reason": result.reason,
+            "written_paths": [str(path) for path in result.written_paths],
+        }
+
     def has_pending_continuation(self) -> bool:
         """Return True when the conversation ends with tool results awaiting a follow-up model turn."""
         if not self._messages:
@@ -176,6 +233,7 @@ async def submit_message(self, prompt: str | ConversationMessage) -> AsyncIterat
         )
         if user_message.text.strip() and not self._tool_metadata.pop("_suppress_next_user_goal", False):
             remember_user_goal(self._tool_metadata, user_message.text)
+        self._prepare_session_memory()
         self._messages = sanitize_conversation_messages(self._messages)
         self._messages.append(user_message)
         if self._hook_executor is not None:
@@ -215,10 +273,13 @@ async def submit_message(self, prompt: str | ConversationMessage) -> AsyncIterat
                     self._cost_tracker.add(usage)
                 yield event
         finally:
+            await self._update_session_memory()
+            await self._extract_durable_memories()
             self._schedule_auto_dream()
 
     async def continue_pending(self, *, max_turns: int | None = None) -> AsyncIterator[StreamEvent]:
         """Continue an interrupted tool loop without appending a new user message."""
+        self._prepare_session_memory()
         self._messages = sanitize_conversation_messages(self._messages)
         context = QueryContext(
             api_client=self._api_client,
@@ -241,3 +302,5 @@ async def continue_pending(self, *, max_turns: int | None = None) -> AsyncIterat
             if usage is not None:
                 self._cost_tracker.add(usage)
             yield event
+        await self._update_session_memory()
+        await self._extract_durable_memories()