Skip to content

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

feat(sessions): add async commit support with wait parameter (#472)

dr3243636-ops9c4f419bcc04
diff --git a/openviking/server/routers/sessions.py b/openviking/server/routers/sessions.py
index 29b5f64f7..1dab60752 100644
--- a/openviking/server/routers/sessions.py
+++ b/openviking/server/routers/sessions.py
@@ -2,9 +2,11 @@
# SPDX-License-Identifier: Apache-2.0
"""Sessions endpoints for OpenViking HTTP Server."""
+import asyncio
+import logging
from typing import Any, Dict, List, Literal, Optional
-from fastapi import APIRouter, Depends, Path
+from fastapi import APIRouter, Depends, Path, Query
from pydantic import BaseModel, model_validator
from openviking.message.part import TextPart, part_from_dict
@@ -14,6 +16,7 @@ from openviking.server.identity import RequestContext
from openviking.server.models import Response
router = APIRouter(prefix="/api/v1/sessions", tags=["sessions"])
+logger = logging.getLogger(__name__)
class TextPartRequest(BaseModel):
@@ -141,12 +144,46 @@ async def delete_session(
@router.post("/{session_id}/commit")
async def commit_session(
session_id: str = Path(..., description="Session ID"),
+ wait: bool = Query(
+ True,
+ description="If False, commit runs in background and returns immediately",
+ ),
_ctx: RequestContext = Depends(get_request_context),
):
- """Commit a session (archive and extract memories)."""
+ """Commit a session (archive and extract memories).
+
+ When wait=False, the commit is processed in the background.
+ This is useful for avoiding blocking when the commit involves
+ LLM calls for memory extraction.
+ """
service = get_service()
- result = await service.sessions.commit(session_id, _ctx)
- return Response(status="ok", result=result)
+ if wait:
+ result = await service.sessions.commit_async(session_id, _ctx)
+ return Response(status="ok", result=result)
+
+ asyncio.create_task(_background_commit(service, session_id, _ctx))
+ return Response(
+ status="ok",
+ result={
+ "session_id": session_id,
+ "status": "accepted",
+ "message": "Commit is processing in the background",
+ },
+ )
+
+
+async def _background_commit(service, session_id: str, ctx: RequestContext) -> None:
+ """Run session commit in background."""
+ try:
+ result = await service.sessions.commit_async(session_id, ctx)
+ memories = result.get("memories_extracted", 0)
+ logger.info(
+ "Background commit completed: session=%s, memories=%d",
+ session_id,
+ memories,
+ )
+ except Exception:
+ logger.exception("Background commit failed: session=%s", session_id)
@router.post("/{session_id}/extract")
diff --git a/openviking/service/session_service.py b/openviking/service/session_service.py
index 74b16514f..ca5460211 100644
--- a/openviking/service/session_service.py
+++ b/openviking/service/session_service.py
@@ -134,15 +134,33 @@ class SessionService:
async def commit(self, session_id: str, ctx: RequestContext) -> Dict[str, Any]:
"""Commit a session (archive messages and extract memories).
+ Delegates to commit_async() for true non-blocking behavior.
+
Args:
session_id: Session ID to commit
Returns:
Commit result
"""
+ return await self.commit_async(session_id, ctx)
+
+ async def commit_async(self, session_id: str, ctx: RequestContext) -> Dict[str, Any]:
+ """Async commit a session without blocking the event loop.
+
+ Unlike the previous implementation which used run_async() (blocking
+ the calling thread during LLM calls), this method uses native async/await
+ throughout, keeping the event loop free to serve other requests.
+
+ Args:
+ session_id: Session ID to commit
+
+ Returns:
+ Commit result with keys: session_id, status, memories_extracted,
+ active_count_updated, archived, stats
+ """
self._ensure_initialized()
session = await self.get(session_id, ctx)
- return session.commit()
+ return await session.commit_async()
async def extract(self, session_id: str, ctx: RequestContext) -> List[Any]:
"""Extract memories from a session.
diff --git a/openviking/session/session.py b/openviking/session/session.py
index 62679223e..243069a14 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -294,6 +294,80 @@ class Session:
logger.info(f"Session {self.session_id} committed")
return result
+ async def commit_async(self) -> Dict[str, Any]:
+ """Async commit session: create archive, extract memories, persist."""
+ result = {
+ "session_id": self.session_id,
+ "status": "committed",
+ "memories_extracted": 0,
+ "active_count_updated": 0,
+ "archived": False,
+ "stats": None,
+ }
+ if not self._messages:
+ return result
+
+ # 1. Archive current messages
+ self._compression.compression_index += 1
+ messages_to_archive = self._messages.copy()
+
+ summary = await self._generate_archive_summary_async(messages_to_archive)
+ archive_abstract = self._extract_abstract_from_summary(summary)
+ archive_overview = summary
+
+ await self._write_archive_async(
+ index=self._compression.compression_index,
+ messages=messages_to_archive,
+ abstract=archive_abstract,
+ overview=archive_overview,
+ )
+
+ self._compression.original_count += len(messages_to_archive)
+ result["archived"] = True
+
+ self._messages.clear()
+ logger.info(
+ f"Archived: {len(messages_to_archive)} messages → history/archive_{self._compression.compression_index:03d}/"
+ )
+
+ # 2. Extract long-term memories
+ if self._session_compressor:
+ logger.info(
+ f"Starting memory extraction from {len(messages_to_archive)} archived messages"
+ )
+ memories = await self._session_compressor.extract_long_term_memories(
+ messages=messages_to_archive,
+ user=self.user,
+ session_id=self.session_id,
+ ctx=self.ctx,
+ )
+ logger.info(f"Extracted {len(memories)} memories")
+ result["memories_extracted"] = len(memories)
+ self._stats.memories_extracted += len(memories)
+
+ # 3. Write current messages to AGFS
+ await self._write_to_agfs_async(self._messages)
+
+ # 4. Create relations
+ await self._write_relations_async()
+
+ # 5. Update active_count
+ active_count_updated = await self._update_active_counts_async()
+ result["active_count_updated"] = active_count_updated
+
+ # 6. Update statistics
+ self._stats.compression_count = self._compression.compression_index
+ result["stats"] = {
+ "total_turns": self._stats.total_turns,
+ "contexts_used": self._stats.contexts_used,
+ "skills_used": self._stats.skills_used,
+ "memories_extracted": self._stats.memories_extracted,
+ }
+
+ self._stats.total_tokens = 0
+ logger.info(f"Session {self.session_id} committed (async)")
+ return result
+
def _update_active_counts(self) -> int:
"""Update active_count for used contexts/skills."""
if not self._vikingdb_manager:
@@ -310,6 +384,22 @@ class Session:
logger.info(f"Updated active_count for {updated} contexts/skills")
return updated
+ async def _update_active_counts_async(self) -> int:
+ """Async update active_count for used contexts/skills."""
+ if not self._vikingdb_manager:
+ return 0
+
+ uris = [usage.uri for usage in self._usage_records if usage.uri]
+ try:
+ updated = await self._vikingdb_manager.increment_active_count(self.ctx, uris)
+ except Exception as e:
+ logger.debug(f"Could not update active_count for usage URIs: {e}")
+ updated = 0
+
+ if updated > 0:
+ logger.info(f"Updated active_count for {updated} contexts/skills")
+ return updated
+
async def get_context_for_search(
self, query: str, max_archives: int = 3, max_messages: int = 20
) -> Dict[str, Any]:
@@ -403,6 +493,29 @@ class Session:
turn_count = len([m for m in messages if m.role == "user"])
return f"# Session Summary\n\n**Overview**: {turn_count} turns, {len(messages)} messages"
+ async def _generate_archive_summary_async(self, messages: List[Message]) -> str:
+ """Generate structured summary for archive (async)."""
+ if not messages:
+ return ""
+
+ formatted = "\n".join([f"[{m.role}]: {m.content}" for m in messages])
+
+ vlm = get_openviking_config().vlm
+ if vlm and vlm.is_available():
+ try:
+ from openviking.prompts import render_prompt
+
+ prompt = render_prompt(
+ "compression.structured_summary",
+ {"messages": formatted},
+ )
+ return await vlm.get_completion_async(prompt)
+ except Exception as e:
+ logger.warning(f"LLM summary failed: {e}")
+
+ turn_count = len([m for m in messages if m.role == "user"])
+ return f"# Session Summary\n\n**Overview**: {turn_count} turns, {len(messages)} messages"
+
def _write_archive(
self,
index: int,
@@ -436,6 +549,39 @@ class Session:
logger.debug(f"Written archive: {archive_uri}")
+ async def _write_archive_async(
+ self,
+ index: int,
+ messages: List[Message],
+ abstract: str,
+ overview: str,
+ ) -> None:
+ """Write archive to history/archive_N/ (async)."""
+ if not self._viking_fs:
+ return
+
+ viking_fs = self._viking_fs
+ archive_uri = f"{self._session_uri}/history/archive_{index:03d}"
+
+ lines = [m.to_jsonl() for m in messages]
+ await viking_fs.write_file(
+ uri=f"{archive_uri}/messages.jsonl",
+ content="\n".join(lines) + "\n",
+ ctx=self.ctx,
+ )
+ await viking_fs.write_file(
+ uri=f"{archive_uri}/.abstract.md",
+ content=abstract,
+ ctx=self.ctx,
+ )
+ await viking_fs.write_file(
+ uri=f"{archive_uri}/.overview.md",
+ content=overview,
+ ctx=self.ctx,
+ )
+
+ logger.debug(f"Written archive: {archive_uri}")
+
def _write_to_agfs(self, messages: List[Message]) -> None:
"""Write messages.jsonl to AGFS."""
if not self._viking_fs:
@@ -474,6 +620,36 @@ class Session:
)
)
+ async def _write_to_agfs_async(self, messages: List[Message]) -> None:
+ """Write messages.jsonl to AGFS (async)."""
+ if not self._viking_fs:
+ return
+
+ viking_fs = self._viking_fs
+ turn_count = len([m for m in messages if m.role == "user"])
+
+ abstract = self._generate_abstract()
+ overview = self._generate_overview(turn_count)
+
+ lines = [m.to_jsonl() for m in messages]
+ content = "\n".join(lines) + "\n" if lines else ""
+
+ await viking_fs.write_file(
+ uri=f"{self._session_uri}/messages.jsonl",
+ content=content,
+ ctx=self.ctx,
+ )
+ await viking_fs.write_file(
+ uri=f"{self._session_uri}/.abstract.md",
+ content=abstract,
+ ctx=self.ctx,
+ )
+ await viking_fs.write_file(
+ uri=f"{self._session_uri}/.overview.md",
+ content=overview,
+ ctx=self.ctx,
+ )
+
def _append_to_jsonl(self, msg: Message) -> None:
"""Append to messages.jsonl."""
if not self._viking_fs:
@@ -581,6 +757,19 @@ class Session:
except Exception as e:
logger.warning(f"Failed to create relation to {usage.uri}: {e}")
+ async def _write_relations_async(self) -> None:
+ """Create relations to used contexts/tools (async)."""
+ if not self._viking_fs:
+ return
+
+ viking_fs = self._viking_fs
+ for usage in self._usage_records:
+ try:
+ await viking_fs.link(self._session_uri, usage.uri, ctx=self.ctx)
+ logger.debug(f"Created relation: {self._session_uri} -> {usage.uri}")
+ except Exception as e:
+ logger.warning(f"Failed to create relation to {usage.uri}: {e}")
+
# ============= Properties =============
@property
diff --git a/tests/test_session_async_commit.py b/tests/test_session_async_commit.py
new file mode 100644
index 000000000..4de752eb8
--- /dev/null
+++ b/tests/test_session_async_commit.py
@@ -0,0 +1,140 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for async session commit support."""
+
+import asyncio
+import time
+from typing import AsyncGenerator, Tuple
+
+import httpx
+import pytest_asyncio
+
+from openviking import AsyncOpenViking
+from openviking.message import TextPart
+from openviking.server.app import create_app
+from openviking.server.config import ServerConfig
+from openviking.server.dependencies import set_service
+from openviking.service.core import OpenVikingService
+
+
+@pytest_asyncio.fixture
+async def api_client(temp_dir) -> AsyncGenerator[Tuple[httpx.AsyncClient, OpenVikingService], None]:
+ """Create in-process HTTP client for API endpoint tests."""
+ service = OpenVikingService(path=str(temp_dir / "api_data"))
+ await service.initialize()
+ app = create_app(config=ServerConfig(), service=service)
+ set_service(service)
+
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+ yield client, service
+
+ await service.close()
+ await AsyncOpenViking.reset()
+
+
+@pytest_asyncio.fixture
+async def ov_client(temp_dir) -> AsyncGenerator[AsyncOpenViking, None]:
+ """Create AsyncOpenViking client for unit tests."""
+ client = AsyncOpenViking(path=str(temp_dir / "ov_data"))
+ await client.initialize()
+ yield client
+ await client.close()
+ await AsyncOpenViking.reset()
+
+
+async def _new_session_with_one_message(client: httpx.AsyncClient) -> str:
+ create_resp = await client.post("/api/v1/sessions", json={})
+ assert create_resp.status_code == 200
+ session_id = create_resp.json()["result"]["session_id"]
+
+ add_resp = await client.post(
+ f"/api/v1/sessions/{session_id}/messages",
+ json={"role": "user", "content": "hello"},
+ )
+ assert add_resp.status_code == 200
+ return session_id
+
+
+async def test_commit_async_returns_same_shape_as_commit(ov_client: AsyncOpenViking):
+ """commit_async should keep result schema compatible with commit."""
+ session = ov_client.session(session_id="async-shape-test")
+ session.add_message("user", [TextPart("first")])
+ sync_result = session.commit()
+
+ session.add_message("user", [TextPart("second")])
+ async_result = await session.commit_async()
+
+ assert set(sync_result.keys()) == set(async_result.keys())
+ assert async_result["status"] == "committed"
+
+
+async def test_commit_endpoint_wait_false_returns_accepted_immediately(api_client):
+ """wait=false should return immediately and run commit in background."""
+ client, service = api_client
+ session_id = await _new_session_with_one_message(client)
+
+ done = asyncio.Event()
+
+ async def fake_commit_async(_sid, _ctx):
+ await asyncio.sleep(0.2)
+ done.set()
+ return {"session_id": _sid, "status": "committed", "memories_extracted": 0}
+
+ service.sessions.commit_async = fake_commit_async # type: ignore[method-assign]
+
+ start = time.perf_counter()
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ elapsed = time.perf_counter() - start
+
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["status"] == "ok"
+ assert body["result"]["status"] == "accepted"
+ assert elapsed < 0.15
+
+ await asyncio.wait_for(done.wait(), timeout=1.0)
+
+
+async def test_commit_endpoint_wait_true_waits_for_result(api_client):
+ """wait=true should wait and return full commit result."""
+ client, service = api_client
+ session_id = await _new_session_with_one_message(client)
+
+ async def fake_commit_async(_sid, _ctx):
+ await asyncio.sleep(0.05)
+ return {
+ "session_id": _sid,
+ "status": "committed",
+ "memories_extracted": 2,
+ "active_count_updated": 1,
+ "archived": True,
+ "stats": {},
+ }
+
+ service.sessions.commit_async = fake_commit_async # type: ignore[method-assign]
+
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": True})
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["status"] == "ok"
+ assert body["result"]["status"] == "committed"
+ assert body["result"]["memories_extracted"] == 2
+
+
+async def test_commit_endpoint_default_wait_true_backward_compatible(api_client):
+ """No wait param should behave like previous blocking commit API."""
+ client, service = api_client
+ session_id = await _new_session_with_one_message(client)
+
+ async def fake_commit_async(_sid, _ctx):
+ return {"session_id": _sid, "status": "committed", "memories_extracted": 1}
+
+ service.sessions.commit_async = fake_commit_async # type: ignore[method-assign]
+
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["status"] == "ok"
+ assert body["result"]["status"] == "committed"