Skip to content

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

feat(session): async commit, session metadata, and archive continuity threading (#900)

Qin Haojie2c598e88c558
diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.md
index 1e9bd4235..7c4526980 100644
--- a/docs/en/api/05-sessions.md
+++ b/docs/en/api/05-sessions.md
@@ -101,27 +101,30 @@ openviking session list
### get_session()
-Get session details.
+Get session details. Returns NOT_FOUND when the session does not exist by default. Pass `auto_create=True` to create it automatically.
**Parameters**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| session_id | str | Yes | - | Session ID |
+| auto_create | bool | No | False | Whether to auto-create the session if it does not exist |
**Python SDK (Embedded / HTTP)**
```python
-# Load existing session
-session = client.session(session_id="a1b2c3d4")
-session.load()
-print(f"Loaded {len(session.messages)} messages")
+# Get existing session (raises NotFoundError if not found)
+info = client.get_session("a1b2c3d4")
+print(f"Messages: {info['message_count']}, Commits: {info['commit_count']}")
+
+# Get or create session
+info = client.get_session("a1b2c3d4", auto_create=True)
```
**HTTP API**
```
-GET /api/v1/sessions/{session_id}
+GET /api/v1/sessions/{session_id}?auto_create=false
```
```bash
@@ -142,10 +145,32 @@ openviking session get a1b2c3d4
"status": "ok",
"result": {
"session_id": "a1b2c3d4",
- "user": "alice",
- "message_count": 5
- },
- "time": 0.1
+ "created_at": "2026-03-23T10:00:00+08:00",
+ "updated_at": "2026-03-23T11:30:00+08:00",
+ "message_count": 5,
+ "commit_count": 3,
+ "memories_extracted": {
+ "profile": 1,
+ "preferences": 2,
+ "entities": 3,
+ "events": 1,
+ "cases": 2,
+ "patterns": 1,
+ "tools": 0,
+ "skills": 0,
+ "total": 10
+ },
+ "last_commit_at": "2026-03-23T11:00:00+08:00",
+ "llm_token_usage": {
+ "prompt_tokens": 5200,
+ "completion_tokens": 1800,
+ "total_tokens": 7000
+ },
+ "user": {
+ "user_id": "alice",
+ "agent_id": "default"
+ }
+ }
}
```
@@ -395,7 +420,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \
### commit()
-Commit a session by archiving messages and extracting memories.
+Commit a session. Message archiving (Phase 1) completes immediately. Summary generation and memory extraction (Phase 2) run asynchronously in the background. Returns a `task_id` for polling progress.
**Parameters**
@@ -409,10 +434,15 @@ Commit a session by archiving messages and extracting memories.
session = client.session(session_id="a1b2c3d4")
session.load()
-# Commit archives messages and extracts memories
+# Commit returns immediately with task_id; summary + memory extraction runs in background
result = session.commit()
-print(f"Status: {result['status']}")
-print(f"Memories extracted: {result['memories_extracted']}")
+print(f"Status: {result['status']}") # "accepted"
+print(f"Task ID: {result['task_id']}")
+
+# Poll background task progress
+task = client.get_task(result["task_id"])
+if task["status"] == "completed":
+ print(f"Memories extracted: {task['result']['memories_extracted']}")
```
**HTTP API**
@@ -422,9 +452,14 @@ POST /api/v1/sessions/{session_id}/commit
```
```bash
+# Commit session (returns immediately)
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/commit \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key"
+
+# Poll task status
+curl -X GET http://localhost:1933/api/v1/tasks/{task_id} \
+ -H "X-API-Key: your-key"
```
**CLI**
@@ -440,10 +475,73 @@ openviking session commit a1b2c3d4
"status": "ok",
"result": {
"session_id": "a1b2c3d4",
- "status": "committed",
+ "status": "accepted",
+ "task_id": "uuid-xxx",
+ "archive_uri": "viking://session/a1b2c3d4/history/archive_001",
"archived": true
- },
- "time": 0.1
+ }
+}
+```
+
+---
+
+### get_task()
+
+Query background task status (e.g., commit summary generation and memory extraction progress).
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| task_id | str | Yes | - | Task ID (returned by commit) |
+
+**Python SDK (Embedded / HTTP)**
+
+```python
+task = client.get_task(task_id)
+print(f"Status: {task['status']}") # "pending" | "running" | "completed" | "failed"
+```
+
+**HTTP API**
+
+```
+GET /api/v1/tasks/{task_id}
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \
+ -H "X-API-Key: your-key"
+```
+
+**Response (in progress)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "uuid-xxx",
+ "task_type": "session_commit",
+ "status": "running"
+ }
+}
+```
+
+**Response (completed)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "uuid-xxx",
+ "task_type": "session_commit",
+ "status": "completed",
+ "result": {
+ "session_id": "a1b2c3d4",
+ "archive_uri": "viking://session/a1b2c3d4/history/archive_001",
+ "memories_extracted": 5,
+ "active_count_updated": 2
+ }
+ }
}
```
@@ -475,9 +573,10 @@ viking://session/{session_id}/
+-- .relations.json # Related contexts
+-- history/ # Archived history
+-- archive_001/
- | +-- messages.jsonl
- | +-- .abstract.md
- | +-- .overview.md
+ | +-- messages.jsonl # Written in Phase 1
+ | +-- .abstract.md # Written in Phase 2 (background)
+ | +-- .overview.md # Written in Phase 2 (background)
+ | +-- .done # Phase 2 completion marker
+-- archive_002/
```
@@ -532,9 +631,14 @@ session.add_message("assistant", [
# Track actually used contexts
session.used(contexts=[results.resources[0].uri])
-# Commit session (archive messages, extract memories)
+# Commit session (returns immediately; summary + memory extraction runs in background)
result = session.commit()
-print(f"Memories extracted: {result['memories_extracted']}")
+print(f"Task ID: {result['task_id']}")
+
+# Optional: poll for completion
+task = client.get_task(result["task_id"])
+if task and task["status"] == "completed":
+ print(f"Memories extracted: {task['result']['memories_extracted']}")
client.close()
```
@@ -572,10 +676,15 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \
-H "X-API-Key: your-key" \
-d '{"contexts": ["viking://resources/docs/embedding/"]}'
-# Step 6: Commit session
+# Step 6: Commit session (returns immediately with task_id)
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/commit \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key"
+# Returns: {"status": "ok", "result": {"status": "accepted", "task_id": "uuid-xxx", ...}}
+
+# Step 7: Poll background task progress (optional)
+curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \
+ -H "X-API-Key: your-key"
```
## Best Practices
diff --git a/docs/en/concepts/08-session.md b/docs/en/concepts/08-session.md
index 38737edfc..1b6a59027 100644
--- a/docs/en/concepts/08-session.md
+++ b/docs/en/concepts/08-session.md
@@ -6,6 +6,8 @@ Session manages conversation messages, tracks context usage, and extracts long-t
**Lifecycle**: Create → Interact → Commit
+Getting a session by ID will auto-create it if it does not exist.
+
```python
session = client.session(session_id="chat_001")
session.add_message("user", [TextPart("...")])
@@ -18,7 +20,8 @@ session.commit()
|--------|-------------|
| `add_message(role, parts)` | Add message |
| `used(contexts, skill)` | Record used contexts/skills |
-| `commit()` | Commit: archive + memory extraction |
+| `commit()` | Commit: archive (sync) + summary generation and memory extraction (async background) |
+| `get_task(task_id)` | Query background task status |
### add_message
@@ -57,11 +60,15 @@ session.used(skill={
```python
result = session.commit()
# {
-# "status": "committed",
-# "memories_extracted": 5,
-# "active_count_updated": 2,
+# "status": "accepted",
+# "task_id": "uuid-xxx",
+# "archive_uri": "viking://session/.../history/archive_001",
# "archived": True
# }
+
+# Poll background task progress
+task = client.get_task(result["task_id"])
+# task["status"]: "pending" | "running" | "completed" | "failed"
```
## Message Structure
@@ -89,12 +96,19 @@ class Message:
### Archive Flow
-Auto-archive on commit():
+commit() executes in two phases:
+**Phase 1 (synchronous, returns immediately)**:
1. Increment compression_index
-2. Copy current messages to archive directory
-3. Generate structured summary (LLM)
-4. Clear current messages list
+2. Write messages to archive directory (`messages.jsonl`)
+3. Clear current messages list
+4. Return `task_id`
+
+**Phase 2 (asynchronous background)**:
+5. Generate structured summary (LLM) → write `.abstract.md` and `.overview.md`
+6. Extract long-term memories
+7. Update active_count
+8. Write `.done` completion marker
### Summary Format
@@ -160,9 +174,10 @@ viking://session/{session_id}/
├── .overview.md # Current overview
├── history/
│ ├── archive_001/
-│ │ ├── messages.jsonl
-│ │ ├── .abstract.md
-│ │ └── .overview.md
+│ │ ├── messages.jsonl # Written in Phase 1
+│ │ ├── .abstract.md # Written in Phase 2 (background)
+│ │ ├── .overview.md # Written in Phase 2 (background)
+│ │ └── .done # Phase 2 completion marker
│ └── archive_NNN/
└── tools/
└── {tool_id}/tool.json
diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.md
index 48cada3a7..2ec116466 100644
--- a/docs/zh/api/05-sessions.md
+++ b/docs/zh/api/05-sessions.md
@@ -101,27 +101,30 @@ openviking session list
### get_session()
-获取会话详情。
+获取会话详情。默认当会话不存在时返回 NOT_FOUND 错误,可通过 `auto_create=True` 自动创建。
**参数**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| session_id | str | 是 | - | 会话 ID |
+| auto_create | bool | 否 | False | 会话不存在时是否自动创建 |
**Python SDK (Embedded / HTTP)**
```python
-# 加载已有会话
-session = client.session(session_id="a1b2c3d4")
-session.load()
-print(f"Loaded {len(session.messages)} messages")
+# 获取已有会话(不存在时抛 NotFoundError)
+info = client.get_session("a1b2c3d4")
+print(f"Messages: {info['message_count']}, Commits: {info['commit_count']}")
+
+# 获取或创建会话
+info = client.get_session("a1b2c3d4", auto_create=True)
```
**HTTP API**
```
-GET /api/v1/sessions/{session_id}
+GET /api/v1/sessions/{session_id}?auto_create=false
```
```bash
@@ -142,10 +145,32 @@ openviking session get a1b2c3d4
"status": "ok",
"result": {
"session_id": "a1b2c3d4",
- "user": "alice",
- "message_count": 5
- },
- "time": 0.1
+ "created_at": "2026-03-23T10:00:00+08:00",
+ "updated_at": "2026-03-23T11:30:00+08:00",
+ "message_count": 5,
+ "commit_count": 3,
+ "memories_extracted": {
+ "profile": 1,
+ "preferences": 2,
+ "entities": 3,
+ "events": 1,
+ "cases": 2,
+ "patterns": 1,
+ "tools": 0,
+ "skills": 0,
+ "total": 10
+ },
+ "last_commit_at": "2026-03-23T11:00:00+08:00",
+ "llm_token_usage": {
+ "prompt_tokens": 5200,
+ "completion_tokens": 1800,
+ "total_tokens": 7000
+ },
+ "user": {
+ "user_id": "alice",
+ "agent_id": "default"
+ }
+ }
}
```
@@ -395,7 +420,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \
### commit()
-提交会话,归档消息并提取记忆。
+提交会话。归档消息(Phase 1)立即完成,摘要生成和记忆提取(Phase 2)在后台异步执行。返回 `task_id` 用于查询后台任务进度。
**参数**
@@ -409,10 +434,15 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \
session = client.session(session_id="a1b2c3d4")
session.load()
-# commit 会归档消息并提取记忆
+# commit 立即返回 task_id,后台异步执行摘要生成和记忆提取
result = session.commit()
-print(f"Status: {result['status']}")
-print(f"Memories extracted: {result['memories_extracted']}")
+print(f"Status: {result['status']}") # "accepted"
+print(f"Task ID: {result['task_id']}")
+
+# 查询后台任务进度
+task = client.get_task(result["task_id"])
+if task["status"] == "completed":
+ print(f"Memories extracted: {task['result']['memories_extracted']}")
```
**HTTP API**
@@ -422,9 +452,14 @@ POST /api/v1/sessions/{session_id}/commit
```
```bash
+# 提交会话(立即返回)
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/commit \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key"
+
+# 查询任务状态
+curl -X GET http://localhost:1933/api/v1/tasks/{task_id} \
+ -H "X-API-Key: your-key"
```
**CLI**
@@ -440,10 +475,73 @@ openviking session commit a1b2c3d4
"status": "ok",
"result": {
"session_id": "a1b2c3d4",
- "status": "committed",
+ "status": "accepted",
+ "task_id": "uuid-xxx",
+ "archive_uri": "viking://session/a1b2c3d4/history/archive_001",
"archived": true
- },
- "time": 0.1
+ }
+}
+```
+
+---
+
+### get_task()
+
+查询后台任务状态(如 commit 的摘要生成和记忆提取进度)。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| task_id | str | 是 | - | 任务 ID(由 commit 返回) |
+
+**Python SDK (Embedded / HTTP)**
+
+```python
+task = client.get_task(task_id)
+print(f"Status: {task['status']}") # "pending" | "running" | "completed" | "failed"
+```
+
+**HTTP API**
+
+```
+GET /api/v1/tasks/{task_id}
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \
+ -H "X-API-Key: your-key"
+```
+
+**响应(进行中)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "uuid-xxx",
+ "task_type": "session_commit",
+ "status": "running"
+ }
+}
+```
+
+**响应(完成)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "uuid-xxx",
+ "task_type": "session_commit",
+ "status": "completed",
+ "result": {
+ "session_id": "a1b2c3d4",
+ "archive_uri": "viking://session/a1b2c3d4/history/archive_001",
+ "memories_extracted": 5,
+ "active_count_updated": 2
+ }
+ }
}
```
@@ -475,9 +573,10 @@ viking://session/{session_id}/
+-- .relations.json # 关联上下文
+-- history/ # 归档历史
+-- archive_001/
- | +-- messages.jsonl
- | +-- .abstract.md
- | +-- .overview.md
+ | +-- messages.jsonl # Phase 1 写入
+ | +-- .abstract.md # Phase 2 写入(后台)
+ | +-- .overview.md # Phase 2 写入(后台)
+ | +-- .done # Phase 2 完成标记
+-- archive_002/
```
@@ -532,9 +631,14 @@ session.add_message("assistant", [
# 跟踪实际使用的上下文
session.used(contexts=[results.resources[0].uri])
-# 提交会话(归档消息、提取记忆)
+# 提交会话(立即返回,后台执行摘要生成和记忆提取)
result = session.commit()
-print(f"Memories extracted: {result['memories_extracted']}")
+print(f"Task ID: {result['task_id']}")
+
+# 可选:等待后台任务完成
+task = client.get_task(result["task_id"])
+if task and task["status"] == "completed":
+ print(f"Memories extracted: {task['result']['memories_extracted']}")
client.close()
```
@@ -572,10 +676,15 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \
-H "X-API-Key: your-key" \
-d '{"contexts": ["viking://resources/docs/embedding/"]}'
-# 步骤 6:提交会话
+# 步骤 6:提交会话(立即返回 task_id)
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/commit \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key"
+# 返回:{"status": "ok", "result": {"status": "accepted", "task_id": "uuid-xxx", ...}}
+
+# 步骤 7:查询后台任务进度(可选)
+curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \
+ -H "X-API-Key: your-key"
```
## 最佳实践
diff --git a/docs/zh/concepts/08-session.md b/docs/zh/concepts/08-session.md
index 7d524cd99..d8f00d3aa 100644
--- a/docs/zh/concepts/08-session.md
+++ b/docs/zh/concepts/08-session.md
@@ -6,6 +6,8 @@ Session 负责管理对话消息、记录上下文使用、提取长期记忆。
**生命周期**:创建 → 交互 → 提交
+通过 session_id 获取会话时,如果会话不存在将自动创建。
+
```python
session = client.session(session_id="chat_001")
session.add_message("user", [TextPart("...")])
@@ -18,7 +20,8 @@ session.commit()
|------|------|
| `add_message(role, parts)` | 添加消息 |
| `used(contexts, skill)` | 记录使用的上下文/技能 |
-| `commit()` | 提交:归档 + 记忆提取 |
+| `commit()` | 提交:归档(同步) + 摘要生成和记忆提取(异步后台) |
+| `get_task(task_id)` | 查询后台任务状态 |
### add_message
@@ -57,11 +60,15 @@ session.used(skill={
```python
result = session.commit()
# {
-# "status": "committed",
-# "memories_extracted": 5,
-# "active_count_updated": 2,
+# "status": "accepted",
+# "task_id": "uuid-xxx",
+# "archive_uri": "viking://session/.../history/archive_001",
# "archived": True
# }
+
+# 查询后台任务进度
+task = client.get_task(result["task_id"])
+# task["status"]: "pending" | "running" | "completed" | "failed"
```
## 消息结构
@@ -89,12 +96,19 @@ class Message:
### 归档流程
-commit() 时自动归档:
+commit() 分两阶段执行:
+**Phase 1(同步,立即完成)**:
1. 递增 compression_index
-2. 复制当前消息到归档目录
-3. 生成结构化摘要(LLM)
-4. 清空当前消息列表
+2. 写入消息到归档目录(`messages.jsonl`)
+3. 清空当前消息列表
+4. 返回 `task_id`
+
+**Phase 2(异步后台)**:
+5. 生成结构化摘要(LLM)→ 写入 `.abstract.md` 和 `.overview.md`
+6. 提取长期记忆
+7. 更新 active_count
+8. 写入 `.done` 完成标记
### 摘要格式
@@ -159,9 +173,10 @@ viking://session/{session_id}/
├── .overview.md # 当前概览
├── history/
│ ├── archive_001/
-│ │ ├── messages.jsonl
-│ │ ├── .abstract.md
-│ │ └── .overview.md
+│ │ ├── messages.jsonl # Phase 1 写入
+│ │ ├── .abstract.md # Phase 2 写入(后台)
+│ │ ├── .overview.md # Phase 2 写入(后台)
+│ │ └── .done # Phase 2 完成标记
│ └── archive_NNN/
└── tools/
└── {tool_id}/tool.json
diff --git a/examples/openclaw-plugin/client.ts b/examples/openclaw-plugin/client.ts
index edc11f48b..11187dd96 100644
--- a/examples/openclaw-plugin/client.ts
+++ b/examples/openclaw-plugin/client.ts
@@ -58,37 +58,22 @@ export function isMemoryUri(uri: string): boolean {
}
export class OpenVikingClient {
- private resolvedSpaceByScope: Partial<Record<ScopeName, string>> = {};
- private runtimeIdentity: RuntimeIdentity | null = null;
+ private spaceCache = new Map<string, Partial<Record<ScopeName, string>>>();
+ private identityCache = new Map<string, RuntimeIdentity>();
constructor(
private readonly baseUrl: string,
private readonly apiKey: string,
- private agentId: string,
+ private readonly defaultAgentId: string,
private readonly timeoutMs: number,
) {}
- /**
- * Dynamically switch the agent identity for multi-agent memory isolation.
- * When a shared client serves multiple agents (e.g. in OpenClaw multi-agent
- * gateway), call this before each agent's recall/capture to route memories
- * to the correct agent_space = md5(user_id + agent_id)[:12].
- * Clears cached space resolution so the next request re-derives agent_space.
- */
- setAgentId(newAgentId: string): void {
- if (newAgentId && newAgentId !== this.agentId) {
- this.agentId = newAgentId;
- // Clear cached identity and spaces — they depend on agentId
- this.runtimeIdentity = null;
- this.resolvedSpaceByScope = {};
- }
- }
-
- getAgentId(): string {
- return this.agentId;
+ getDefaultAgentId(): string {
+ return this.defaultAgentId;
}
- private async request<T>(path: string, init: RequestInit = {}): Promise<T> {
+ private async request<T>(path: string, init: RequestInit = {}, agentId?: string): Promise<T> {
+ const effectiveAgentId = agentId ?? this.defaultAgentId;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), this.timeoutMs);
try {
@@ -96,8 +81,8 @@ export class OpenVikingClient {
if (this.apiKey) {
headers.set("X-API-Key", this.apiKey);
}
- if (this.agentId) {
- headers.set("X-OpenViking-Agent", this.agentId);
+ if (effectiveAgentId) {
+ headers.set("X-OpenViking-Agent", effectiveAgentId);
}
if (init.body && !headers.has("Content-Type")) {
headers.set("Content-Type", "application/json");
@@ -131,44 +116,57 @@ export class OpenVikingClient {
await this.request<{ status: string }>("/health");
}
- private async ls(uri: string): Promise<Array<Record<string, unknown>>> {
+ private async ls(uri: string, agentId?: string): Promise<Array<Record<string, unknown>>> {
return this.request<Array<Record<string, unknown>>>(
`/api/v1/fs/ls?uri=${encodeURIComponent(uri)}&output=original`,
+ {},
+ agentId,
);
}
- private async getRuntimeIdentity(): Promise<RuntimeIdentity> {
- if (this.runtimeIdentity) {
- return this.runtimeIdentity;
+ private async getRuntimeIdentity(agentId?: string): Promise<RuntimeIdentity> {
+ const effectiveAgentId = agentId ?? this.defaultAgentId;
+ const cached = this.identityCache.get(effectiveAgentId);
+ if (cached) {
+ return cached;
}
- const fallback: RuntimeIdentity = { userId: "default", agentId: this.agentId || "default" };
+ const fallback: RuntimeIdentity = { userId: "default", agentId: effectiveAgentId || "default" };
try {
- const status = await this.request<{ user?: unknown }>("/api/v1/system/status");
+ const status = await this.request<{ user?: unknown }>("/api/v1/system/status", {}, agentId);
const userId =
typeof status.user === "string" && status.user.trim() ? status.user.trim() : "default";
- this.runtimeIdentity = { userId, agentId: this.agentId || "default" };
- return this.runtimeIdentity;
+ const identity: RuntimeIdentity = { userId, agentId: effectiveAgentId || "default" };
+ this.identityCache.set(effectiveAgentId, identity);
+ return identity;
} catch {
- this.runtimeIdentity = fallback;
+ this.identityCache.set(effectiveAgentId, fallback);
return fallback;
}
}
- private async resolveScopeSpace(scope: ScopeName): Promise<string> {
- const cached = this.resolvedSpaceByScope[scope];
+ private async resolveScopeSpace(scope: ScopeName, agentId?: string): Promise<string> {
+ const effectiveAgentId = agentId ?? this.defaultAgentId;
+ const agentScopes = this.spaceCache.get(effectiveAgentId);
+ const cached = agentScopes?.[scope];
if (cached) {
return cached;
}
- const identity = await this.getRuntimeIdentity();
+ const identity = await this.getRuntimeIdentity(agentId);
const fallbackSpace =
scope === "user" ? identity.userId : md5Short(`${identity.userId}:${identity.agentId}`);
const reservedDirs = scope === "user" ? USER_STRUCTURE_DIRS : AGENT_STRUCTURE_DIRS;
const preferredSpace =
scope === "user" ? identity.userId : md5Short(`${identity.userId}:${identity.agentId}`);
+ const saveSpace = (space: string) => {
+ const existing = this.spaceCache.get(effectiveAgentId) ?? {};
+ existing[scope] = space;
+ this.spaceCache.set(effectiveAgentId, existing);
+ };
+
try {
- const entries = await this.ls(`viking://${scope}`);
+ const entries = await this.ls(`viking://${scope}`, agentId);
const spaces = entries
.filter((entry) => entry?.isDir === true)
.map((entry) => (typeof entry.name === "string" ? entry.name.trim() : ""))
@@ -176,15 +174,15 @@ export class OpenVikingClient {
if (spaces.length > 0) {
if (spaces.includes(preferredSpace)) {
- this.resolvedSpaceByScope[scope] = preferredSpace;
+ saveSpace(preferredSpace);
return preferredSpace;
}
if (scope === "user" && spaces.includes("default")) {
- this.resolvedSpaceByScope[scope] = "default";
+ saveSpace("default");
return "default";
}
if (spaces.length === 1) {
- this.resolvedSpaceByScope[scope] = spaces[0]!;
+ saveSpace(spaces[0]!);
return spaces[0]!;
}
}
@@ -192,11 +190,11 @@ export class OpenVikingClient {
// Fall back to identity-derived space when listing fails.
}
- this.resolvedSpaceByScope[scope] = fallbackSpace;
+ saveSpace(fallbackSpace);
return fallbackSpace;
}
- private async normalizeTargetUri(targetUri: string): Promise<string> {
+ private async normalizeTargetUri(targetUri: string, agentId?: string): Promise<string> {
const trimmed = targetUri.trim().replace(/\/+$/, "");
const match = trimmed.match(/^viking:\/\/(user|agent)(?:\/(.*))?$/);
if (!match) {
@@ -217,7 +215,7 @@ export class OpenVikingClient {
return trimmed;
}
- const space = await this.resolveScopeSpace(scope);
+ const space = await this.resolveScopeSpace(scope, agentId);
return `viking://${scope}/${space}/${parts.join("/")}`;
}
@@ -228,8 +226,9 @@ export class OpenVikingClient {
limit: number;
scoreThreshold?: number;
},
+ agentId?: string,
): Promise<FindResult> {
- const normalizedTargetUri = await this.normalizeTargetUri(options.targetUri);
+ const normalizedTargetUri = await this.normalizeTargetUri(options.targetUri, agentId);
const body = {
query,
target_uri: normalizedTargetUri,
@@ -239,55 +238,74 @@ export class OpenVikingClient {
return this.request<FindResult>("/api/v1/search/find", {
method: "POST",
body: JSON.stringify(body),
- });
+ }, agentId);
}
- async read(uri: string): Promise<string> {
+ async read(uri: string, agentId?: string): Promise<string> {
return this.request<string>(
`/api/v1/content/read?uri=${encodeURIComponent(uri)}`,
+ {},
+ agentId,
);
}
- async createSession(): Promise<string> {
- const result = await this.request<{ session_id: string }>("/api/v1/sessions", {
- method: "POST",
- body: JSON.stringify({}),
- });
- return result.session_id;
- }
-
- async addSessionMessage(sessionId: string, role: string, content: string): Promise<void> {
+ async addSessionMessage(sessionId: string, role: string, content: string, agentId?: string): Promise<void> {
await this.request<{ session_id: string }>(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
{
method: "POST",
body: JSON.stringify({ role, content }),
},
+ agentId,
);
}
- /** GET session so server loads messages from storage before extract (workaround for AGFS visibility). */
- async getSession(sessionId: string): Promise<{ message_count?: number }> {
+ /** GET session — server auto-creates if absent; also loads messages from storage before extract. */
+ async getSession(sessionId: string, agentId?: string): Promise<{ message_count?: number }> {
return this.request<{ message_count?: number }>(
`/api/v1/sessions/${encodeURIComponent(sessionId)}`,
{ method: "GET" },
+ agentId,
);
}
- async extractSessionMemories(sessionId: string): Promise<Array<Record<string, unknown>>> {
- return this.request<Array<Record<string, unknown>>>(
- `/api/v1/sessions/${encodeURIComponent(sessionId)}/extract`,
- { method: "POST", body: JSON.stringify({}) },
- );
+ /**
+ * Commit a session: archive (Phase 1) and extract memories (Phase 2).
+ * wait=false (default): Phase 2 runs in background, returns task_id for polling.
+ * wait=true: blocks until Phase 2 completes, returns memories_extracted count.
+ */
+ async commitSession(
+ sessionId: string,
+ options?: { wait?: boolean; agentId?: string },
+ ): Promise<{
+ session_id: string;
+ status: string;
+ task_id?: string;
+ archive_uri?: string;
+ archived?: boolean;
+ memories_extracted?: number;
+ }> {
+ const wait = options?.wait ?? false;
+ return this.request<{
+ session_id: string;
+ status: string;
+ task_id?: string;
+ archive_uri?: string;
+ archived?: boolean;
+ memories_extracted?: number;
+ }>(`/api/v1/sessions/${encodeURIComponent(sessionId)}/commit?wait=${wait}`, {
+ method: "POST",
+ body: JSON.stringify({}),
+ }, options?.agentId);
}
- async deleteSession(sessionId: string): Promise<void> {
- await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" });
+ async deleteSession(sessionId: string, agentId?: string): Promise<void> {
+ await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" }, agentId);
}
- async deleteUri(uri: string): Promise<void> {
+ async deleteUri(uri: string, agentId?: string): Promise<void> {
await this.request(`/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=false`, {
method: "DELETE",
- });
+ }, agentId);
}
}
diff --git a/examples/openclaw-plugin/context-engine.ts b/examples/openclaw-plugin/context-engine.ts
index cae34e694..738dd2281 100644
--- a/examples/openclaw-plugin/context-engine.ts
+++ b/examples/openclaw-plugin/context-engine.ts
@@ -7,7 +7,6 @@ import {
import {
trimForLog,
toJsonLog,
- summarizeExtractedMemories,
} from "./memory-ranking.js";
type AgentMessage = {
@@ -73,6 +72,15 @@ type ContextEngine = {
}) => Promise<CompactResult>;
};
+export type ContextEngineWithSessionMapping = ContextEngine & {
+ /** Return the OV session ID for an OpenClaw sessionKey (identity: sessionKey IS the OV session ID). */
+ getOVSessionForKey: (sessionKey: string) => string;
+ /** Ensure an OV session exists on the server for the given OpenClaw sessionKey (auto-created by getSession if absent). */
+ resolveOVSession: (sessionKey: string) => Promise<string>;
+ /** Commit (extract + archive) then delete the OV session, so a fresh one is created on next use. */
+ commitOVSession: (sessionKey: string) => Promise<void>;
+};
+
type Logger = {
info: (msg: string) => void;
warn?: (msg: string) => void;
@@ -134,7 +142,7 @@ export function createMemoryOpenVikingContextEngine(params: {
logger: Logger;
getClient: () => Promise<OpenVikingClient>;
resolveAgentId: (sessionId: string) => string;
-}): ContextEngine {
+}): ContextEngineWithSessionMapping {
const {
id,
name,
@@ -145,16 +153,27 @@ export function createMemoryOpenVikingContextEngine(params: {
resolveAgentId,
} = params;
- const switchClientAgent = async (sessionId: string, phase: "assemble" | "afterTurn") => {
- const client = await getClient();
- const resolvedAgentId = resolveAgentId(sessionId);
- const before = client.getAgentId();
- if (resolvedAgentId && resolvedAgentId !== before) {
- client.setAgentId(resolvedAgentId);
- logger.info(`openviking: switched to agentId=${resolvedAgentId} for ${phase}`);
+ async function doCommitOVSession(sessionKey: string): Promise<void> {
+ try {
+ const client = await getClient();
+ const agentId = resolveAgentId(sessionKey);
+ const commitResult = await client.commitSession(sessionKey, { wait: true, agentId });
+ logger.info(
+ `openviking: committed OV session for sessionKey=${sessionKey}, archived=${commitResult.archived ?? false}, memories=${commitResult.memories_extracted ?? 0}, task_id=${commitResult.task_id ?? "none"}`,
+ );
+ await client.deleteSession(sessionKey, agentId).catch(() => {});
+ } catch (err) {
+ warnOrInfo(logger, `openviking: commit failed for sessionKey=${sessionKey}: ${String(err)}`);
}
- return client;
- };
+ }
+
+ function extractSessionKey(runtimeContext: Record<string, unknown> | undefined): string | undefined {
+ if (!runtimeContext) {
+ return undefined;
+ }
+ const key = runtimeContext.sessionKey;
+ return typeof key === "string" && key.trim() ? key.trim() : undefined;
+ }
return {
info: {
@@ -163,13 +182,23 @@ export function createMemoryOpenVikingContextEngine(params: {
version,
},
+ // --- session-mapping extensions ---
+
+ getOVSessionForKey: (sessionKey: string) => sessionKey,
+
+ async resolveOVSession(sessionKey: string): Promise<string> {
+ return sessionKey;
+ },
+
+ commitOVSession: doCommitOVSession,
+
+ // --- standard ContextEngine methods ---
+
async ingest(): Promise<IngestResult> {
- // Keep canonical capture behavior in afterTurn (same semantics as old agent_end hook).
return { ingested: false };
},
async ingestBatch(): Promise<IngestBatchResult> {
- // Keep canonical capture behavior in afterTurn (same semantics as old agent_end hook).
return { ingestedCount: 0 };
},
@@ -186,7 +215,8 @@ export function createMemoryOpenVikingContextEngine(params: {
}
try {
- await switchClientAgent(afterTurnParams.sessionId, "afterTurn");
+ const sessionKey = extractSessionKey(afterTurnParams.runtimeContext);
+ const agentId = resolveAgentId(sessionKey ?? afterTurnParams.sessionId);
const messages = afterTurnParams.messages ?? [];
if (messages.length === 0) {
@@ -222,33 +252,14 @@ export function createMemoryOpenVikingContextEngine(params: {
}
const client = await getClient();
- const sessionId = await client.createSession();
- try {
- await client.addSessionMessage(sessionId, "user", decision.normalizedText);
- await client.getSession(sessionId).catch(() => ({}));
- const extracted = await client.extractSessionMemories(sessionId);
-
- logger.info(
- `openviking: auto-captured ${newCount} new messages, extracted ${extracted.length} memories`,
- );
- logger.info(
- `openviking: capture-detail ${toJsonLog({
- capturedCount: newCount,
- captured: [trimForLog(turnText, 260)],
- extractedCount: extracted.length,
- extracted: summarizeExtractedMemories(extracted),
- })}`,
- );
- if (extracted.length === 0) {
- warnOrInfo(
- logger,
- "openviking: auto-capture completed but extract returned 0 memories. " +
- "Check OpenViking server logs for embedding/extract errors.",
- );
- }
- } finally {
- await client.deleteSession(sessionId).catch(() => {});
- }
+ const OVSessionId = sessionKey ?? afterTurnParams.sessionId;
+ await client.addSessionMessage(OVSessionId, "user", decision.normalizedText, agentId);
+ const commitResult = await client.commitSession(OVSessionId, { wait: true, agentId });
+ logger.info(
+ `openviking: committed ${newCount} messages in session=${OVSessionId}, ` +
+ `archived=${commitResult.archived ?? false}, memories=${commitResult.memories_extracted ?? 0}, ` +
+ `task_id=${commitResult.task_id ?? "none"} ${toJsonLog({ captured: [trimForLog(turnText, 260)] })}`,
+ );
} catch (err) {
warnOrInfo(logger, `openviking: auto-capture failed: ${String(err)}`);
}
diff --git a/examples/openclaw-plugin/index.ts b/examples/openclaw-plugin/index.ts
index d30a95b5f..70fcd09ab 100644
--- a/examples/openclaw-plugin/index.ts
+++ b/examples/openclaw-plugin/index.ts
@@ -27,6 +27,7 @@ import {
prepareLocalPort,
} from "./process-manager.js";
import { createMemoryOpenVikingContextEngine } from "./context-engine.js";
+import type { ContextEngineWithSessionMapping } from "./context-engine.js";
type PluginLogger = {
debug?: (message: string) => void;
@@ -238,6 +239,7 @@ const contextEnginePlugin = {
text: Type.String({ description: "Information to store as memory source text" }),
role: Type.Optional(Type.String({ description: "Session role, default user" })),
sessionId: Type.Optional(Type.String({ description: "Existing OpenViking session ID" })),
+ sessionKey: Type.Optional(Type.String({ description: "OpenClaw sessionKey — uses the persistent 1:1 mapped OV session" })),
}),
async execute(_toolCallId: string, params: Record<string, unknown>) {
const { text } = params as { text: string };
@@ -246,46 +248,50 @@ const contextEnginePlugin = {
? (params as { role: string }).role
: "user";
const sessionIdIn = (params as { sessionId?: string }).sessionId;
+ const sessionKeyIn = (params as { sessionKey?: string }).sessionKey;
api.logger.info?.(
- `openviking: memory_store invoked (textLength=${text?.length ?? 0}, sessionId=${sessionIdIn ?? "temp"})`,
+ `openviking: memory_store invoked (textLength=${text?.length ?? 0}, sessionId=${sessionIdIn ?? "auto"}, sessionKey=${sessionKeyIn ?? "none"})`,
);
let sessionId = sessionIdIn;
- let createdTempSession = false;
+ let usedMappedSession = false;
+ const storeAgentId = sessionKeyIn ? resolveAgentId(sessionKeyIn) : undefined;
try {
const c = await getClient();
+ if (!sessionId && sessionKeyIn && contextEngineRef) {
+ sessionId = await contextEngineRef.resolveOVSession(sessionKeyIn);
+ usedMappedSession = true;
+ }
if (!sessionId) {
- sessionId = await c.createSession();
- createdTempSession = true;
+ return {
+ content: [{ type: "text", text: "Either sessionKey or sessionId is required to store memory." }],
+ details: { action: "rejected", reason: "missing_session_identifier" },
+ };
}
- await c.addSessionMessage(sessionId, role, text);
- const extracted = await c.extractSessionMemories(sessionId);
- if (extracted.length === 0) {
+ await c.addSessionMessage(sessionId, role, text, storeAgentId);
+ const commitResult = await c.commitSession(sessionId, { wait: true, agentId: storeAgentId });
+ const memoriesCount = commitResult.memories_extracted ?? 0;
+ if (memoriesCount === 0) {
api.logger.warn(
- `openviking: memory_store completed but extract returned 0 memories (sessionId=${sessionId}). ` +
+ `openviking: memory_store committed but 0 memories extracted (sessionId=${sessionId}). ` +
"Check OpenViking server logs for embedding/extract errors (e.g. 401 API key, or extraction pipeline).",
);
} else {
- api.logger.info?.(`openviking: memory_store extracted ${extracted.length} memories`);
+ api.logger.info?.(`openviking: memory_store committed, memories=${memoriesCount}`);
}
return {
content: [
{
type: "text",
- text: `Stored in OpenViking session ${sessionId} and extracted ${extracted.length} memories.`,
+ text: `Stored in OpenViking session ${sessionId} and committed ${memoriesCount} memories.`,
},
],
- details: { action: "stored", sessionId, extractedCount: extracted.length, extracted },
+ details: { action: "stored", sessionId, memoriesCount, archived: commitResult.archived ?? false, usedMappedSession },
};
} catch (err) {
api.logger.warn(`openviking: memory_store failed: ${String(err)}`);
throw err;
- } finally {
- if (createdTempSession && sessionId) {
- const c = await getClient().catch(() => null);
- if (c) await c.deleteSession(sessionId!).catch(() => {});
- }
}
},
},
@@ -394,6 +400,8 @@ const contextEnginePlugin = {
},
{ name: "memory_forget" },
);
+ let contextEngineRef: ContextEngineWithSessionMapping | null = null;
+
const sessionAgentIds = new Map<string, string>();
const rememberSessionAgentId = (ctx: {
agentId?: string;
@@ -423,7 +431,7 @@ const contextEnginePlugin = {
rememberSessionAgentId(ctx ?? {});
const hookSessionId = ctx?.sessionId ?? ctx?.sessionKey ?? "";
- const resolvedAgentId = resolveAgentId(hookSessionId);
+ const agentId = resolveAgentId(hookSessionId);
let client: OpenVikingClient;
try {
client = await withTimeout(
@@ -435,10 +443,6 @@ const contextEnginePlugin = {
api.logger.warn?.(`openviking: failed to get client: ${String(err)}`);
return;
}
- if (resolvedAgentId && client.getAgentId() !== resolvedAgentId) {
- client.setAgentId(resolvedAgentId);
- api.logger.info(`openviking: switched to agentId=${resolvedAgentId} for before_prompt_build`);
- }
const eventObj = (event ?? {}) as { messages?: unknown[]; prompt?: string };
const queryText =
@@ -466,12 +470,12 @@ const contextEnginePlugin = {
targetUri: "viking://user/memories",
limit: candidateLimit,
scoreThreshold: 0,
- }),
+ }, agentId),
client.find(queryText, {
targetUri: "viking://agent/memories",
limit: candidateLimit,
scoreThreshold: 0,
- }),
+ }, agentId),
]);
const userResult = userSettled.status === "fulfilled" ? userSettled.value : { memories: [] };
@@ -497,7 +501,7 @@ const contextEnginePlugin = {
if (memories.length > 0) {
const { lines: memoryLines, estimatedTokens } = await buildMemoryLinesWithBudget(
memories,
- (uri) => client.read(uri),
+ (uri) => client.read(uri, agentId),
{
recallPreferAbstract: cfg.recallPreferAbstract,
recallMaxContentChars: cfg.recallMaxContentChars,
@@ -556,16 +560,24 @@ const contextEnginePlugin = {
api.on("agent_end", async (_event: unknown, ctx?: HookAgentContext) => {
rememberSessionAgentId(ctx ?? {});
});
- api.on("before_reset", async (_event: unknown, _ctx?: HookAgentContext) => {
- // Reserved hook registration for future memory flush/reset handling.
+ api.on("before_reset", async (_event: unknown, ctx?: HookAgentContext) => {
+ const sessionKey = ctx?.sessionKey;
+ if (sessionKey && contextEngineRef) {
+ try {
+ await contextEngineRef.commitOVSession(sessionKey);
+ api.logger.info(`openviking: committed OV session on reset for sessionKey=${sessionKey}`);
+ } catch (err) {
+ api.logger.warn(`openviking: failed to commit OV session on reset: ${String(err)}`);
+ }
+ }
});
api.on("after_compaction", async (_event: unknown, _ctx?: HookAgentContext) => {
// Reserved hook registration for future post-compaction memory integration.
});
if (typeof api.registerContextEngine === "function") {
- api.registerContextEngine(contextEnginePlugin.id, () =>
- createMemoryOpenVikingContextEngine({
+ api.registerContextEngine(contextEnginePlugin.id, () => {
+ contextEngineRef = createMemoryOpenVikingContextEngine({
id: contextEnginePlugin.id,
name: contextEnginePlugin.name,
version: "0.1.0",
@@ -573,10 +585,11 @@ const contextEnginePlugin = {
logger: api.logger,
getClient,
resolveAgentId,
- }),
- );
+ });
+ return contextEngineRef;
+ });
api.logger.info(
- "openviking: registered context-engine (before_prompt_build=auto-recall, afterTurn=auto-capture)",
+ "openviking: registered context-engine (before_prompt_build=auto-recall, afterTurn=auto-capture, sessionKey=1:1 mapping)",
);
} else {
api.logger.warn(
diff --git a/openviking/async_client.py b/openviking/async_client.py
index 655a717ea..72bb3c00a 100644
--- a/openviking/async_client.py
+++ b/openviking/async_client.py
@@ -138,10 +138,10 @@ class AsyncOpenViking:
await self._ensure_initialized()
return await self._client.list_sessions()
- async def get_session(self, session_id: str) -> Dict[str, Any]:
+ async def get_session(self, session_id: str, *, auto_create: bool = False) -> Dict[str, Any]:
"""Get session details."""
await self._ensure_initialized()
- return await self._client.get_session(session_id)
+ return await self._client.get_session(session_id, auto_create=auto_create)
async def delete_session(self, session_id: str) -> None:
"""Delete a session."""
@@ -177,6 +177,11 @@ class AsyncOpenViking:
await self._ensure_initialized()
return await self._client.commit_session(session_id, telemetry=telemetry)
+ async def get_task(self, task_id: str) -> Optional[Dict[str, Any]]:
+ """Query background task status."""
+ await self._ensure_initialized()
+ return await self._client.get_task(task_id)
+
# ============= Resource methods =============
async def add_resource(
diff --git a/openviking/client/local.py b/openviking/client/local.py
index 1760f85d7..ca9e8d0ae 100644
--- a/openviking/client/local.py
+++ b/openviking/client/local.py
@@ -321,14 +321,12 @@ class LocalClient(BaseClient):
"""List all sessions."""
return await self._service.sessions.sessions(self._ctx)
- async def get_session(self, session_id: str) -> Dict[str, Any]:
+ async def get_session(self, session_id: str, *, auto_create: bool = False) -> Dict[str, Any]:
"""Get session details."""
- session = await self._service.sessions.get(session_id, self._ctx)
- return {
- "session_id": session.session_id,
- "user": session.user.to_dict(),
- "message_count": len(session.messages),
- }
+ session = await self._service.sessions.get(session_id, self._ctx, auto_create=auto_create)
+ result = session.meta.to_dict()
+ result["user"] = session.user.to_dict()
+ return result
async def delete_session(self, session_id: str) -> None:
"""Delete a session."""
@@ -348,6 +346,10 @@ class LocalClient(BaseClient):
execution.telemetry,
)
+ async def get_task(self, task_id: str) -> Optional[Dict[str, Any]]:
+ """Query background task status."""
+ return await self._service.sessions.get_commit_task(task_id)
+
async def add_message(
self,
session_id: str,
diff --git a/openviking/prompts/templates/compression/structured_summary.yaml b/openviking/prompts/templates/compression/structured_summary.yaml
index 0a8125241..ba9ddf7d1 100644
--- a/openviking/prompts/templates/compression/structured_summary.yaml
+++ b/openviking/prompts/templates/compression/structured_summary.yaml
@@ -7,63 +7,78 @@ metadata:
category: "compression"
variables:
+ - name: "latest_archive_overview"
+ type: "string"
+ description: "Latest completed archive overview"
+ required: false
+ default: ""
- name: "messages"
type: "string"
description: "Session content"
required: true
template: |
- Analyze the following session and generate a structured summary.
+ Analyze the following session archive and generate a structured summary.
+
+ {% if latest_archive_overview %}
+ Latest completed archive overview:
+ {{ latest_archive_overview }}
- Session content:
+ {% endif %}
+ Current archive session content:
{{ messages }}
Please output the summary directly in Markdown format:
# Session Summary
- **One-sentence overview**: [Topic]: [Intent] | [Result] | [Status: Completed/In Progress/Pending]
-
- ## Analysis
- Chronological conversation progress (2-4 key milestones):
- 1. ...
- 2. ...
-
- ## Primary Request and Intent
- User's core objectives:
- - ...
+ **One-sentence overview**: One concise sentence that explains how the current archive continues prior context and what new topics or decisions were added in this archive.
- ## Key Concepts
- Key technical concepts/terms:
+ ## Historical Context Carried Forward
+ Still-valid prior background that should carry into future sessions.
- ...
- ## Context References
- Context referenced in the session (viking:// URIs, external links, etc.):
+ ## New Information In This Archive
+ Important facts, preferences, events, requests, or decisions introduced or updated in the current archive only.
- ...
- ## Errors and Fixes
- Problems encountered and solutions (write "None" if none):
- - Problem → Solution
-
- ## User Messages
- Key user quotes (preserve important expressions):
- - "..."
+ ## Current Archive Analysis
+ Chronological progression within the current archive only (2-4 key milestones).
+ 1. ...
+ 2. ...
- ## Pending Tasks
- Incomplete tasks (write "None" if none):
+ ## Key User Messages
+ Preserve 3-6 important user quotes that remain useful for future continuity.
+ - Include quotes from both prior context and the current archive when relevant.
+ - Prioritize stable preferences, constraints, goals, relationships, and interaction style.
+ - Prefer exact original wording when available from the current archive or prior overview.
- ...
- ## Current Work
- Work in progress at the end of the conversation.
+ ## Open Loops
+ Unresolved items that remain active after this archive. Prefer items newly introduced here, but include older ones if they are still clearly relevant.
+ - ...
## Next Step
- Recommended next actions.
+ Recommended follow-up actions for the assistant or future conversation turns.
+ 1. ...
+ 2. ...
---
Notes:
- - Analysis should reflect the complete timeline
- - User Messages should preserve original quotes
+ - The current archive summary must be continuity-aware, not a standalone recap that ignores prior context.
+ - If latest_archive_overview is provided, first extract 3-6 concise bullets of still-valid background into "Historical Context Carried Forward".
+ - Do not copy the previous overview verbatim. Compress it into durable, reusable context only.
+ - "New Information In This Archive" must focus on what is newly introduced, newly clarified, or newly changed in the current archive.
+ - "Current Archive Analysis" should describe the progression of the current archive itself, not the full historical timeline.
+ - "Key User Messages" should be continuity-aware: do not limit it to the current archive if older user quotes remain important for future turns.
+ - When selecting historical quotes, keep only the most durable and still-relevant ones. Do not repeat quotes that add no future value.
+ - Do not fabricate quotes. Only use wording grounded in the current archive content or in quoted material already present in latest_archive_overview.
+ - Avoid mixing carried-forward background and new information in the same bullet unless the new archive explicitly updates prior context.
+ - If there is no prior overview, write "None" under "Historical Context Carried Forward".
+ - Do not leave placeholder tokens such as [Topic], [Result], or [Status] in the output.
+ - Prefer durable user context: identity, work situation, long-lived preferences, health constraints, ongoing goals, relationship context, recurring interaction preferences.
+ - Do not invent continuity. If a prior detail is not stable or is no longer relevant, omit it.
- Keep overall length within 1000 words
llm_config:
diff --git a/openviking/server/routers/sessions.py b/openviking/server/routers/sessions.py
index bffcf9348..de94d2bf2 100644
--- a/openviking/server/routers/sessions.py
+++ b/openviking/server/routers/sessions.py
@@ -2,11 +2,10 @@
# 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, Body, Depends, Path, Query
+from fastapi import APIRouter, Depends, Path, Query
from pydantic import BaseModel, model_validator
from openviking.message.part import TextPart, part_from_dict
@@ -14,10 +13,7 @@ from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
from openviking.server.models import ErrorInfo, Response
-from openviking.server.telemetry import resolve_selection, run_operation
from openviking.service.task_tracker import get_task_tracker
-from openviking.telemetry import TelemetryRequest
-from openviking_cli.exceptions import InvalidArgumentError
router = APIRouter(prefix="/api/v1/sessions", tags=["sessions"])
logger = logging.getLogger(__name__)
@@ -83,12 +79,6 @@ class UsedRequest(BaseModel):
skill: Optional[Dict[str, Any]] = None
-class CommitSessionRequest(BaseModel):
- """Request model for session commit."""
-
- telemetry: TelemetryRequest = False
-
-
def _to_jsonable(value: Any) -> Any:
"""Convert internal objects (e.g. Context) into JSON-serializable values."""
to_dict = getattr(value, "to_dict", None)
@@ -132,19 +122,23 @@ async def list_sessions(
@router.get("/{session_id}")
async def get_session(
session_id: str = Path(..., description="Session ID"),
+ auto_create: bool = Query(False, description="Create the session if it does not exist"),
_ctx: RequestContext = Depends(get_request_context),
):
"""Get session details."""
+ from openviking_cli.exceptions import NotFoundError
+
service = get_service()
- session = await service.sessions.get(session_id, _ctx)
- return Response(
- status="ok",
- result={
- "session_id": session.session_id,
- "user": session.user.to_dict(),
- "message_count": len(session.messages),
- },
- )
+ try:
+ session = await service.sessions.get(session_id, _ctx, auto_create=auto_create)
+ except NotFoundError:
+ return Response(
+ status="error",
+ error=ErrorInfo(code="NOT_FOUND", message=f"Session {session_id} not found"),
+ )
+ result = session.meta.to_dict()
+ result["user"] = session.user.to_dict()
+ return Response(status="ok", result=result)
@router.delete("/{session_id}")
@@ -160,54 +154,20 @@ async def delete_session(
@router.post("/{session_id}/commit")
async def commit_session(
- request: CommitSessionRequest = Body(default_factory=CommitSessionRequest),
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).
- When wait=False, the commit is processed in the background and a
- ``task_id`` is returned. Use ``GET /tasks/{task_id}`` to poll for
- completion status, results, or errors.
-
- When wait=True (default), the commit blocks until complete and
- returns the full result inline.
+ Archive (Phase 1) completes before returning. Memory extraction
+ (Phase 2) runs in the background. A ``task_id`` is returned for
+ polling progress via ``GET /tasks/{task_id}``.
"""
service = get_service()
tracker = get_task_tracker()
- if wait:
- # Reject if same session already has a background commit running
- if tracker.has_running("session_commit", session_id):
- return Response(
- status="error",
- error=ErrorInfo(
- code="CONFLICT",
- message=f"Session {session_id} already has a commit in progress",
- ),
- )
- execution = await run_operation(
- operation="session.commit",
- telemetry=request.telemetry,
- fn=lambda: service.sessions.commit_async(session_id, _ctx),
- )
- return Response(
- status="ok",
- result=execution.result,
- telemetry=execution.telemetry,
- ).model_dump(exclude_none=True)
-
- selection = resolve_selection(request.telemetry)
- if selection.include_payload:
- raise InvalidArgumentError("telemetry is not supported when wait=false for session.commit")
-
- # Atomically check + create to prevent race conditions
- task = tracker.create_if_no_running("session_commit", session_id)
- if task is None:
+ # Reject if same session already has a commit in progress
+ if tracker.has_running("session_commit", session_id):
return Response(
status="error",
error=ErrorInfo(
@@ -215,44 +175,9 @@ async def commit_session(
message=f"Session {session_id} already has a commit in progress",
),
)
- asyncio.create_task(_background_commit_tracked(service, session_id, _ctx, task.task_id))
-
- return Response(
- status="ok",
- result={
- "session_id": session_id,
- "status": "accepted",
- "task_id": task.task_id,
- "message": "Commit is processing in the background",
- },
- )
-
-async def _background_commit_tracked(
- service, session_id: str, ctx: RequestContext, task_id: str
-) -> None:
- """Run session commit in background with task tracking."""
- tracker = get_task_tracker()
- tracker.start(task_id)
- try:
- result = await service.sessions.commit_async(session_id, ctx)
- tracker.complete(
- task_id,
- {
- "session_id": session_id,
- "memories_extracted": result.get("memories_extracted", 0),
- "archived": result.get("archived", False),
- },
- )
- logger.info(
- "Background commit completed: session=%s task=%s memories=%d",
- session_id,
- task_id,
- result.get("memories_extracted", 0),
- )
- except Exception as exc:
- tracker.fail(task_id, str(exc))
- logger.exception("Background commit failed: session=%s task=%s", session_id, task_id)
+ result = await service.sessions.commit_async(session_id, _ctx)
+ return Response(status="ok", result=result).model_dump(exclude_none=True)
@router.post("/{session_id}/extract")
diff --git a/openviking/service/session_service.py b/openviking/service/session_service.py
index ca5460211..0e23e10ac 100644
--- a/openviking/service/session_service.py
+++ b/openviking/service/session_service.py
@@ -9,6 +9,7 @@ Provides session management operations: session, sessions, add_message, commit,
from typing import Any, Dict, List, Optional
from openviking.server.identity import RequestContext
+from openviking.service.task_tracker import get_task_tracker
from openviking.session import Session
from openviking.session.compressor import SessionCompressor
from openviking.storage import VikingDBManager
@@ -73,14 +74,22 @@ class SessionService:
await session.ensure_exists()
return session
- async def get(self, session_id: str, ctx: RequestContext) -> Session:
+ async def get(
+ self, session_id: str, ctx: RequestContext, *, auto_create: bool = False
+ ) -> Session:
"""Get an existing session.
- Raises NotFoundError when the session does not exist under current user scope.
+ Args:
+ session_id: Session ID
+ ctx: Request context
+ auto_create: If True, create the session when it does not exist.
+ Default is False (raise NotFoundError).
"""
session = self.session(ctx, session_id)
if not await session.exists():
- raise NotFoundError(session_id, "session")
+ if not auto_create:
+ raise NotFoundError(session_id, "session")
+ await session.ensure_exists()
await session.load()
return session
@@ -145,23 +154,27 @@ class SessionService:
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.
+ """Async commit a session.
- 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.
+ Phase 1 (archive) always runs inline. Phase 2 (memory extraction)
+ runs in a background task, returning a task_id for polling.
Args:
session_id: Session ID to commit
Returns:
- Commit result with keys: session_id, status, memories_extracted,
- active_count_updated, archived, stats
+ Commit result with keys: session_id, status, task_id,
+ archive_uri, archived
"""
self._ensure_initialized()
session = await self.get(session_id, ctx)
return await session.commit_async()
+ async def get_commit_task(self, task_id: str) -> Optional[Dict[str, Any]]:
+ """Query background commit task status by task_id."""
+ task = get_task_tracker().get(task_id)
+ return task.to_dict() if task else None
+
async def extract(self, session_id: str, ctx: RequestContext) -> List[Any]:
"""Extract memories from a session.
diff --git a/openviking/session/__init__.py b/openviking/session/__init__.py
index 4dad7c2e2..13eefae7b 100644
--- a/openviking/session/__init__.py
+++ b/openviking/session/__init__.py
@@ -27,7 +27,7 @@ from openviking.session.memory_extractor import (
MemoryExtractor,
ToolSkillCandidateMemory,
)
-from openviking.session.session import Session, SessionCompression, SessionStats
+from openviking.session.session import Session, SessionCompression, SessionMeta, SessionStats
logger = get_logger(__name__)
@@ -74,6 +74,7 @@ __all__ = [
# Session
"Session",
"SessionCompression",
+ "SessionMeta",
"SessionStats",
# Compressor
"SessionCompressor",
diff --git a/openviking/session/compressor.py b/openviking/session/compressor.py
index a55905060..9af225686 100644
--- a/openviking/session/compressor.py
+++ b/openviking/session/compressor.py
@@ -279,12 +279,16 @@ class SessionCompressor:
session_id: Optional[str] = None,
ctx: Optional[RequestContext] = None,
strict_extract_errors: bool = False,
+ latest_archive_overview: str = "",
) -> List[Context]:
"""Extract long-term memories from messages."""
if not messages:
return []
- context = {"messages": messages}
+ context = {
+ "messages": messages,
+ "summary": latest_archive_overview or "",
+ }
if not ctx:
return []
diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.py
index 074ad48be..617acb2b0 100644
--- a/openviking/session/compressor_v2.py
+++ b/openviking/session/compressor_v2.py
@@ -7,21 +7,20 @@ Uses the new Memory Templating System with ReAct orchestrator.
Maintains the same interface as compressor.py for backward compatibility.
"""
-from dataclasses import dataclass
import os
-from typing import Dict, List, Optional
+from dataclasses import dataclass
+from typing import List, Optional
from openviking.core.context import Context
from openviking.message import Message
from openviking.server.identity import RequestContext
+from openviking.session.memory import MemoryReAct, MemoryTypeRegistry, MemoryUpdater
from openviking.storage import VikingDBManager
from openviking.storage.viking_fs import get_viking_fs
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils import get_logger
from openviking_cli.utils.config import get_openviking_config
-from openviking.session.memory import MemoryReAct, MemoryUpdater, MemoryTypeRegistry
-
logger = get_logger(__name__)
@@ -46,15 +45,15 @@ class SessionCompressorV2:
self.vikingdb = vikingdb
# Initialize registry once - used by both MemoryReAct and MemoryUpdater
self._registry = MemoryTypeRegistry()
- schemas_dir = os.path.join(os.path.dirname(__file__), "..", "prompts", "templates", "memory")
+ schemas_dir = os.path.join(
+ os.path.dirname(__file__), "..", "prompts", "templates", "memory"
+ )
self._registry.load_from_directory(schemas_dir)
# Lazy initialize MemoryReAct - we need vlm and ctx
self._react_orchestrator: Optional[MemoryReAct] = None
self._memory_updater: Optional[MemoryUpdater] = None
- def _get_or_create_react(
- self, ctx: Optional[RequestContext] = None
- ) -> MemoryReAct:
+ def _get_or_create_react(self, ctx: Optional[RequestContext] = None) -> MemoryReAct:
"""Create new MemoryReAct instance with current ctx.
Note: Always create new instance to avoid cross-session isolation issues.
@@ -86,6 +85,7 @@ class SessionCompressorV2:
session_id: Optional[str] = None,
ctx: Optional[RequestContext] = None,
strict_extract_errors: bool = False,
+ latest_archive_overview: str = "",
) -> List[Context]:
"""Extract long-term memories from messages using v2 templating system.
@@ -99,8 +99,15 @@ class SessionCompressorV2:
logger.warning("No RequestContext provided, skipping memory extraction")
return []
- # Format conversation as string
- conversation_str = "\n".join([f"[{msg.role}]: {msg.content}" for msg in messages])
+ # Provide the latest completed archive overview as non-actionable history context.
+ conversation_sections: List[str] = []
+ if latest_archive_overview:
+ conversation_sections.append(f"## Previous Archive Overview\n{latest_archive_overview}")
+
+ conversation_sections.append(
+ "\n".join([f"[{msg.role}]: {msg.content}" for msg in messages])
+ )
+ conversation_str = "\n\n".join(section for section in conversation_sections if section)
logger.info("Starting v2 memory extraction from conversation")
@@ -123,9 +130,7 @@ class SessionCompressorV2:
)
# Apply operations
- result = await updater.apply_operations(
- operations, ctx, registry=orchestrator.registry
- )
+ result = await updater.apply_operations(operations, ctx, registry=orchestrator.registry)
logger.info(
f"Applied memory operations: written={len(result.written_uris)}, "
@@ -136,9 +141,7 @@ class SessionCompressorV2:
# Return list with dummy values to preserve count for stats in session.py
# v2 directly writes to storage, so we return None objects to maintain len() accuracy
total_changes = (
- len(result.written_uris)
- + len(result.edited_uris)
- + len(result.deleted_uris)
+ len(result.written_uris) + len(result.edited_uris) + len(result.deleted_uris)
)
return [None] * total_changes
diff --git a/openviking/session/memory/tools.py b/openviking/session/memory/tools.py
index 4a3074b93..8878aa3da 100644
--- a/openviking/session/memory/tools.py
+++ b/openviking/session/memory/tools.py
@@ -37,14 +37,16 @@ def create_tool_call_message(
return {
"role": "assistant",
"content": None,
- "tool_calls": [{
- "id": str(call_id),
- "type": "function",
- "function": {
- "name": tool_name,
- "arguments": json.dumps(params),
- },
- }],
+ "tool_calls": [
+ {
+ "id": str(call_id),
+ "type": "function",
+ "function": {
+ "name": tool_name,
+ "arguments": json.dumps(params),
+ },
+ }
+ ],
}
@@ -102,7 +104,6 @@ def add_tool_call_items_to_messages(
tool_call_items: List of tuples (call_id, tool_name, params, result)
"""
for call_id, tool_name, params, result in tool_call_items:
-
add_tool_call_pair_to_messages(messages, call_id, tool_name, params, result)
@@ -235,7 +236,7 @@ class MemorySearchTool(MemoryTool):
},
"session_info": {
"type": "object",
- "description": "Session information with summaries and recent_messages, optional",
+ "description": "Session information with latest_archive_overview and current_messages, optional",
},
"limit": {
"type": "integer",
@@ -264,7 +265,12 @@ class MemorySearchTool(MemoryTool):
query = kwargs.get("query", "")
target_uri = kwargs.get("target_uri", "")
# If target_uri is empty, use default from ctx
- if not target_uri and ctx and hasattr(ctx, 'default_search_uris') and ctx.default_search_uris:
+ if (
+ not target_uri
+ and ctx
+ and hasattr(ctx, "default_search_uris")
+ and ctx.default_search_uris
+ ):
target_uri = ctx.default_search_uris
session_info = kwargs.get("session_info")
limit = kwargs.get("limit", 10)
@@ -347,15 +353,13 @@ class MemoryLsTool(MemoryTool):
size = e.get("size", 0)
result_lines.append(f"{name} {_format_size(size)}")
if not result_lines:
- return f"Directory is empty. You can write new files to create memory content."
- return '\n'.join(result_lines)
+ return "Directory is empty. You can write new files to create memory content."
+ return "\n".join(result_lines)
except Exception as e:
logger.error(f"Failed to execute ls: {e}")
return {"error": str(e)}
-
-
# Tool registry
MEMORY_TOOLS_REGISTRY: Dict[str, MemoryTool] = {}
diff --git a/openviking/session/memory_extractor.py b/openviking/session/memory_extractor.py
index 147d8f451..9a2406997 100644
--- a/openviking/session/memory_extractor.py
+++ b/openviking/session/memory_extractor.py
@@ -282,11 +282,12 @@ class MemoryExtractor:
output_language = self._detect_output_language(
messages, fallback_language=fallback_language
)
+ history_summary = str(context.get("summary") or "")
prompt = render_prompt(
"compression.memory_extraction",
{
- "summary": "",
+ "summary": history_summary,
"recent_messages": formatted_messages,
"user": user._user_id,
"feedback": "",
@@ -304,7 +305,9 @@ class MemoryExtractor:
request_summary = {
"user": user._user_id,
"output_language": output_language,
+ "summary_len": len(history_summary),
"recent_messages_len": len(formatted_messages),
+ "summary": history_summary,
"recent_messages": formatted_messages,
}
logger.debug("Memory extraction LLM request summary: %s", request_summary)
diff --git a/openviking/session/session.py b/openviking/session/session.py
index e1498057a..f62998c99 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -5,6 +5,7 @@
Session as Context: Sessions integrated into L0/L1/L2 system.
"""
+import asyncio
import json
import re
from dataclasses import dataclass, field
@@ -50,6 +51,79 @@ class SessionStats:
memories_extracted: int = 0
+@dataclass
+class SessionMeta:
+ """Session metadata persisted in .meta.json."""
+
+ session_id: str = ""
+ created_at: str = ""
+ updated_at: str = ""
+ message_count: int = 0
+ commit_count: int = 0
+ memories_extracted: Dict[str, int] = field(
+ default_factory=lambda: {
+ "profile": 0,
+ "preferences": 0,
+ "entities": 0,
+ "events": 0,
+ "cases": 0,
+ "patterns": 0,
+ "tools": 0,
+ "skills": 0,
+ "total": 0,
+ }
+ )
+ last_commit_at: str = ""
+ llm_token_usage: Dict[str, int] = field(
+ default_factory=lambda: {
+ "prompt_tokens": 0,
+ "completion_tokens": 0,
+ "total_tokens": 0,
+ }
+ )
+
+ def to_dict(self) -> Dict[str, Any]:
+ return {
+ "session_id": self.session_id,
+ "created_at": self.created_at,
+ "updated_at": self.updated_at,
+ "message_count": self.message_count,
+ "commit_count": self.commit_count,
+ "memories_extracted": dict(self.memories_extracted),
+ "last_commit_at": self.last_commit_at,
+ "llm_token_usage": dict(self.llm_token_usage),
+ }
+
+ @classmethod
+ def from_dict(cls, data: Dict[str, Any]) -> "SessionMeta":
+ token_usage = data.get("llm_token_usage", {})
+ memories = data.get("memories_extracted", {})
+ return cls(
+ session_id=data.get("session_id", ""),
+ created_at=data.get("created_at", ""),
+ updated_at=data.get("updated_at", ""),
+ message_count=data.get("message_count", 0),
+ commit_count=data.get("commit_count", 0),
+ memories_extracted={
+ "profile": memories.get("profile", 0),
+ "preferences": memories.get("preferences", 0),
+ "entities": memories.get("entities", 0),
+ "events": memories.get("events", 0),
+ "cases": memories.get("cases", 0),
+ "patterns": memories.get("patterns", 0),
+ "tools": memories.get("tools", 0),
+ "skills": memories.get("skills", 0),
+ "total": memories.get("total", 0),
+ },
+ last_commit_at=data.get("last_commit_at", ""),
+ llm_token_usage={
+ "prompt_tokens": token_usage.get("prompt_tokens", 0),
+ "completion_tokens": token_usage.get("completion_tokens", 0),
+ "total_tokens": token_usage.get("total_tokens", 0),
+ },
+ )
+
+
@dataclass
class Usage:
"""Usage record."""
@@ -90,6 +164,7 @@ class Session:
self._usage_records: List[Usage] = []
self._compression: SessionCompression = SessionCompression()
self._stats: SessionStats = SessionStats()
+ self._meta = SessionMeta(session_id=self.session_id, created_at=get_current_timestamp())
self._loaded = False
logger.info(f"Session created: {self.session_id} for user {self.user}")
@@ -126,6 +201,17 @@ class Session:
except Exception:
pass
+ # Load .meta.json
+ try:
+ meta_content = await self._viking_fs.read_file(
+ f"{self._session_uri}/.meta.json", ctx=self.ctx
+ )
+ self._meta = SessionMeta.from_dict(json.loads(meta_content))
+ except Exception:
+ # Old session without meta — derive from existing data
+ self._meta.message_count = len(self._messages)
+ self._meta.commit_count = self._compression.compression_index
+
self._loaded = True
async def exists(self) -> bool:
@@ -142,12 +228,35 @@ class Session:
return
await self._viking_fs.mkdir(self._session_uri, exist_ok=True, ctx=self.ctx)
await self._viking_fs.write_file(f"{self._session_uri}/messages.jsonl", "", ctx=self.ctx)
+ await self._save_meta()
+
+ async def _save_meta(self) -> None:
+ """Persist .meta.json to storage."""
+ if not self._viking_fs:
+ return
+ self._meta.updated_at = get_current_timestamp()
+ await self._viking_fs.write_file(
+ uri=f"{self._session_uri}/.meta.json",
+ content=json.dumps(self._meta.to_dict(), ensure_ascii=False),
+ ctx=self.ctx,
+ )
+
+ def _save_meta_sync(self) -> None:
+ """Sync wrapper for _save_meta()."""
+ if not self._viking_fs:
+ return
+ run_async(self._save_meta())
@property
def messages(self) -> List[Message]:
"""Get message list."""
return self._messages
+ @property
+ def meta(self) -> SessionMeta:
+ """Get session metadata."""
+ return self._meta
+
# ============= Core methods =============
def used(
@@ -195,6 +304,9 @@ class Session:
self._stats.total_tokens += len(msg.content) // 4
self._append_to_jsonl(msg)
+
+ self._meta.message_count = len(self._messages)
+ self._save_meta_sync()
return msg
def update_tool_part(
@@ -224,32 +336,30 @@ class Session:
return run_async(self.commit_async())
async def commit_async(self) -> Dict[str, Any]:
- """Async commit session: two-phase approach.
+ """Async commit session: archive immediately, extract memories in background.
Phase 1 (Archive prep, PathLock-protected): Copy messages, clear live
session, increment compression index. Uses a distributed filesystem lock
(PathLock) so this works across workers and processes.
- Phase 2 (Memory, redo-log protected): Extract memories, write, enqueue.
- """
- import uuid
+ Phase 2 (Memory extraction): Always runs in background via asyncio.create_task().
+ Returns a task_id for tracking Phase 2 progress.
+ """
+ from openviking.service.task_tracker import get_task_tracker
from openviking.storage.transaction import LockContext, get_lock_manager
- result = {
- "session_id": self.session_id,
- "status": "committed",
- "memories_extracted": 0,
- "active_count_updated": 0,
- "archived": False,
- "stats": None,
- }
-
# ===== Phase 1: Snapshot + clear (PathLock-protected) =====
# Fast pre-check: skip lock entirely if no messages (common case avoids
# unnecessary filesystem lock acquisition).
if not self._messages:
get_current_telemetry().set("memory.extracted", 0)
- return result
+ return {
+ "session_id": self.session_id,
+ "status": "accepted",
+ "task_id": None,
+ "archive_uri": None,
+ "archived": False,
+ }
# Use filesystem-based distributed lock so this works across workers/processes.
session_path = self._viking_fs._uri_to_path(self._session_uri, ctx=self.ctx)
@@ -258,7 +368,13 @@ class Session:
# callers both passed the pre-check but only the first should archive.
if not self._messages:
get_current_telemetry().set("memory.extracted", 0)
- return result
+ return {
+ "session_id": self.session_id,
+ "status": "accepted",
+ "task_id": None,
+ "archive_uri": None,
+ "archived": False,
+ }
self._compression.compression_index += 1
messages_to_archive = self._messages.copy()
@@ -274,96 +390,217 @@ class Session:
# Lock released — live session is now clean.
# Any add_message() from here appends to the fresh empty list.
- # ===== Phase 1 continued: Archive write (no lock needed) =====
- summary = await self._generate_archive_summary_async(messages_to_archive)
- archive_abstract = self._extract_abstract_from_summary(summary)
- archive_overview = summary
-
+ # ===== Phase 1 continued: Write raw archive (no LLM calls, no lock needed) =====
archive_uri = (
f"{self._session_uri}/history/archive_{self._compression.compression_index:03d}"
)
- await self._write_archive_async(
- index=self._compression.compression_index,
- messages=messages_to_archive,
- abstract=archive_abstract,
- overview=archive_overview,
- )
+ if self._viking_fs:
+ lines = [m.to_jsonl() for m in messages_to_archive]
+ await self._viking_fs.write_file(
+ uri=f"{archive_uri}/messages.jsonl",
+ content="\n".join(lines) + "\n",
+ ctx=self.ctx,
+ )
+
+ self._meta.message_count = 0
+ await self._save_meta()
self._compression.original_count += len(messages_to_archive)
- result["archived"] = True
logger.info(
f"Archived: {len(messages_to_archive)} messages → "
f"history/archive_{self._compression.compression_index:03d}/"
)
- # ===== Phase 2: Memory extraction + write (redo-log protected) =====
- redo_log = get_lock_manager().redo_log
- task_id = str(uuid.uuid4())
- redo_log.write_pending(
- task_id,
- {
- "archive_uri": archive_uri,
- "session_uri": self._session_uri,
- "account_id": self.ctx.account_id,
- "user_id": self.ctx.user.user_id,
- "agent_id": self.ctx.user.agent_id,
- "role": self.ctx.role.value,
- },
- )
+ # Snapshot mutable state for Phase 2
+ usage_snapshot = self._usage_records.copy()
+ first_message_id = messages_to_archive[0].id if messages_to_archive else ""
+ last_message_id = messages_to_archive[-1].id if messages_to_archive else ""
- 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(
+ # Create TaskRecord for tracking Phase 2
+ tracker = get_task_tracker()
+ task = tracker.create("session_commit", resource_id=self.session_id)
+
+ asyncio.create_task(
+ self._run_memory_extraction(
+ task_id=task.task_id,
+ archive_uri=archive_uri,
messages=messages_to_archive,
- user=self.user,
- session_id=self.session_id,
- ctx=self.ctx,
+ usage_records=usage_snapshot,
+ first_message_id=first_message_id,
+ last_message_id=last_message_id,
)
- logger.info(f"Extracted {len(memories)} memories")
- result["memories_extracted"] = len(memories)
- self._stats.memories_extracted += len(memories)
- get_current_telemetry().set("memory.extracted", len(memories))
-
- await self._write_to_agfs_async(self._messages)
- await self._write_relations_async()
-
- # Enqueue semantic processing directly
- from openviking.storage.queuefs import get_queue_manager
- from openviking.storage.queuefs.semantic_msg import SemanticMsg
-
- queue_manager = get_queue_manager()
- if queue_manager:
- msg = SemanticMsg(
- uri=self._session_uri,
- context_type="memory",
- account_id=self.ctx.account_id,
- user_id=self.ctx.user.user_id,
- agent_id=self.ctx.user.agent_id,
- role=self.ctx.role.value,
- )
- semantic_queue = queue_manager.get_queue(queue_manager.SEMANTIC)
- await semantic_queue.enqueue(msg)
+ )
+
+ return {
+ "session_id": self.session_id,
+ "status": "accepted",
+ "task_id": task.task_id,
+ "archive_uri": archive_uri,
+ "archived": True,
+ }
- redo_log.mark_done(task_id)
+ async def _run_memory_extraction(
+ self,
+ task_id: str,
+ archive_uri: str,
+ messages: List[Message],
+ usage_records: List["Usage"],
+ first_message_id: str,
+ last_message_id: str,
+ ) -> None:
+ """Phase 2: Extract memories, write relations, enqueue — runs in background."""
+ import uuid
- # Update active_count
- active_count_updated = await self._update_active_counts_async()
- result["active_count_updated"] = active_count_updated
+ from openviking.service.task_tracker import get_task_tracker
+ from openviking.storage.transaction import get_lock_manager
+ from openviking.telemetry import OperationTelemetry, bind_telemetry
- # 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,
- }
+ tracker = get_task_tracker()
+ tracker.start(task_id)
- self._stats.total_tokens = 0
- logger.info(f"Session {self.session_id} committed (async)")
- return result
+ memories_extracted: Dict[str, int] = {}
+ active_count_updated = 0
+ telemetry = OperationTelemetry(operation="session_commit_phase2", enabled=True)
+
+ try:
+ with bind_telemetry(telemetry):
+ # redo-log protection
+ redo_task_id = str(uuid.uuid4())
+ redo_log = get_lock_manager().redo_log
+ redo_log.write_pending(
+ redo_task_id,
+ {
+ "archive_uri": archive_uri,
+ "session_uri": self._session_uri,
+ "account_id": self.ctx.account_id,
+ "user_id": self.ctx.user.user_id,
+ "agent_id": self.ctx.user.agent_id,
+ "role": self.ctx.role.value,
+ },
+ )
+
+ latest_archive_overview = await self._get_latest_completed_archive_overview(
+ exclude_archive_uri=archive_uri
+ )
+
+ # Generate summary and write L0/L1 to archive
+ summary = await self._generate_archive_summary_async(
+ messages,
+ latest_archive_overview=latest_archive_overview,
+ )
+ if self._viking_fs and summary:
+ abstract = self._extract_abstract_from_summary(summary)
+ await self._viking_fs.write_file(
+ uri=f"{archive_uri}/.abstract.md",
+ content=abstract,
+ ctx=self.ctx,
+ )
+ await self._viking_fs.write_file(
+ uri=f"{archive_uri}/.overview.md",
+ content=summary,
+ ctx=self.ctx,
+ )
+
+ # Memory extraction
+ if self._session_compressor:
+ logger.info(
+ f"Starting memory extraction from {len(messages)} archived messages"
+ )
+ extracted = await self._session_compressor.extract_long_term_memories(
+ messages=messages,
+ user=self.user,
+ session_id=self.session_id,
+ ctx=self.ctx,
+ latest_archive_overview=latest_archive_overview,
+ )
+ logger.info(f"Extracted {len(extracted)} memories")
+ for ctx_item in extracted:
+ cat = getattr(ctx_item, "category", "") or "unknown"
+ memories_extracted[cat] = memories_extracted.get(cat, 0) + 1
+ self._stats.memories_extracted += len(extracted)
+ get_current_telemetry().set("memory.extracted", len(extracted))
+
+ # Write relations (using snapshot, not self._usage_records)
+ if self._viking_fs:
+ for usage in usage_records:
+ try:
+ await self._viking_fs.link(self._session_uri, usage.uri, ctx=self.ctx)
+ except Exception as e:
+ logger.warning(f"Failed to create relation to {usage.uri}: {e}")
+
+ redo_log.mark_done(redo_task_id)
+
+ # Update active_count (using snapshot, not self._usage_records)
+ if self._vikingdb_manager:
+ uris = [u.uri for u in usage_records if u.uri]
+ try:
+ active_count_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}")
+ if active_count_updated > 0:
+ logger.info(
+ f"Updated active_count for {active_count_updated} contexts/skills"
+ )
+
+ # Phase 2 complete — update meta with telemetry and commit info
+ snapshot = telemetry.finish("ok")
+ if snapshot:
+ llm = snapshot.summary.get("tokens", {}).get("llm", {})
+ self._meta.llm_token_usage["prompt_tokens"] += llm.get("input", 0)
+ self._meta.llm_token_usage["completion_tokens"] += llm.get("output", 0)
+ self._meta.llm_token_usage["total_tokens"] += llm.get("total", 0)
+ self._meta.commit_count = self._compression.compression_index
+ for cat, count in memories_extracted.items():
+ self._meta.memories_extracted[cat] = (
+ self._meta.memories_extracted.get(cat, 0) + count
+ )
+ self._meta.memories_extracted["total"] = (
+ self._meta.memories_extracted.get("total", 0) + count
+ )
+ self._meta.last_commit_at = get_current_timestamp()
+ self._meta.message_count = len(self._messages)
+ await self._save_meta()
+
+ # Write .done file last — signals that all state is finalized
+ await self._write_done_file(archive_uri, first_message_id, last_message_id)
+
+ tracker.complete(
+ task_id,
+ {
+ "session_id": self.session_id,
+ "archive_uri": archive_uri,
+ "memories_extracted": memories_extracted,
+ "active_count_updated": active_count_updated,
+ },
+ )
+ logger.info(f"Session {self.session_id} memory extraction completed")
+ except Exception as e:
+ tracker.fail(task_id, str(e))
+ logger.exception(f"Memory extraction failed for session {self.session_id}")
+
+ async def _write_done_file(
+ self,
+ archive_uri: str,
+ first_message_id: str,
+ last_message_id: str,
+ ) -> None:
+ """Write .done marker file to the archive directory."""
+ if not self._viking_fs:
+ return
+ content = json.dumps(
+ {
+ "starting_message_id": first_message_id,
+ "ending_message_id": last_message_id,
+ },
+ ensure_ascii=False,
+ )
+ await self._viking_fs.write_file(
+ uri=f"{archive_uri}/.done",
+ content=content,
+ ctx=self.ctx,
+ )
def _update_active_counts(self) -> int:
"""Update active_count for used contexts/skills."""
@@ -397,64 +634,72 @@ class Session:
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]:
+ async def get_context_for_search(self, query: str, max_messages: int = 20) -> Dict[str, Any]:
"""Get session context for intent analysis.
Args:
- query: Query string for matching relevant archives
- max_archives: Maximum number of archives to retrieve (default 3)
- max_messages: Maximum number of messages to retrieve (default 20)
+ query: Query string for the current request.
+ max_messages: Maximum number of current messages to retrieve (default 20)
Returns:
- - summaries: Most relevant and recent archive overview list (List[str])
- - recent_messages: Recent message list (List[Message])
+ - latest_archive_overview: Latest completed archive overview, if any
+ - current_messages: Current message list (List[Message])
"""
- # 1. Recent messages
- recent_messages = list(self._messages[-max_messages:]) if self._messages else []
-
- # 2. Find most relevant and recent archives using query
- summaries = []
- if self.compression.compression_index > 0:
- try:
- history_items = await self._viking_fs.ls(
- f"{self._session_uri}/history", ctx=self.ctx
- )
- query_lower = query.lower()
-
- # Collect all archives with relevance scores
- scored_archives = []
- for item in history_items:
- name = item.get("name") if isinstance(item, dict) else item
- if name and name.startswith("archive_"):
- overview_uri = f"{self._session_uri}/history/{name}/.overview.md"
- try:
- overview = await self._viking_fs.read_file(overview_uri, ctx=self.ctx)
- # Calculate relevance by keyword matching
- score = 0
- if query_lower in overview.lower():
- score = overview.lower().count(query_lower)
- # Infer time from name (higher archive_NNN = newer)
- archive_num = int(name.split("_")[1]) if "_" in name else 0
- scored_archives.append((score, archive_num, overview))
- except Exception:
- pass
-
- # Sort: relevance first, then time, take top N
- scored_archives.sort(key=lambda x: (x[0], x[1]), reverse=True)
- summaries = [overview for _, _, overview in scored_archives[:max_archives]]
+ del query # Current query no longer affects historical archive selection.
- except Exception:
- pass
+ current_messages = list(self._messages[-max_messages:]) if self._messages else []
+ latest_archive_overview = await self._get_latest_completed_archive_overview()
return {
- "summaries": summaries,
- "recent_messages": recent_messages,
+ "latest_archive_overview": latest_archive_overview,
+ "current_messages": current_messages,
}
# ============= Internal methods =============
+ async def _get_latest_completed_archive_overview(
+ self,
+ exclude_archive_uri: Optional[str] = None,
+ ) -> str:
+ """Return the newest completed archive overview, skipping incomplete archives."""
+ if not self._viking_fs or self.compression.compression_index <= 0:
+ return ""
+
+ try:
+ history_items = await self._viking_fs.ls(f"{self._session_uri}/history", ctx=self.ctx)
+ except Exception:
+ return ""
+
+ archive_names: List[str] = []
+ for item in history_items:
+ name = item.get("name") if isinstance(item, dict) else item
+ if name and name.startswith("archive_"):
+ archive_names.append(name)
+
+ def _archive_index(name: str) -> int:
+ try:
+ return int(name.split("_")[1])
+ except Exception:
+ return -1
+
+ exclude = exclude_archive_uri.rstrip("/") if exclude_archive_uri else None
+ for name in sorted(archive_names, key=_archive_index, reverse=True):
+ archive_uri = f"{self._session_uri}/history/{name}"
+ if exclude and archive_uri == exclude:
+ continue
+ try:
+ await self._viking_fs.read_file(f"{archive_uri}/.done", ctx=self.ctx)
+ overview = await self._viking_fs.read_file(
+ f"{archive_uri}/.overview.md",
+ ctx=self.ctx,
+ )
+ if overview:
+ return overview
+ except Exception:
+ continue
+
+ return ""
+
def _extract_abstract_from_summary(self, summary: str) -> str:
"""Extract one-sentence overview from structured summary."""
if not summary:
@@ -467,7 +712,11 @@ class Session:
first_line = summary.split("\n")[0].strip()
return first_line if first_line else ""
- def _generate_archive_summary(self, messages: List[Message]) -> str:
+ def _generate_archive_summary(
+ self,
+ messages: List[Message],
+ latest_archive_overview: str = "",
+ ) -> str:
"""Generate structured summary for archive."""
if not messages:
return ""
@@ -481,7 +730,10 @@ class Session:
prompt = render_prompt(
"compression.structured_summary",
- {"messages": formatted},
+ {
+ "messages": formatted,
+ "latest_archive_overview": latest_archive_overview,
+ },
)
return run_async(vlm.get_completion_async(prompt))
except Exception as e:
@@ -490,7 +742,11 @@ 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:
+ async def _generate_archive_summary_async(
+ self,
+ messages: List[Message],
+ latest_archive_overview: str = "",
+ ) -> str:
"""Generate structured summary for archive (async)."""
if not messages:
return ""
@@ -504,7 +760,10 @@ class Session:
prompt = render_prompt(
"compression.structured_summary",
- {"messages": formatted},
+ {
+ "messages": formatted,
+ "latest_archive_overview": latest_archive_overview,
+ },
)
return await vlm.get_completion_async(prompt)
except Exception as e:
@@ -546,39 +805,6 @@ 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:
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index 4e96e14c4..98c505b94 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -965,12 +965,10 @@ class VikingFS:
# Use first URI for context inference and access check
primary_target_uri = target_uri_list[0] if target_uri_list else ""
- summary_list = session_info.get("summaries") if session_info else None
- if isinstance(summary_list, list):
- session_summary = "\n\n".join(str(item) for item in summary_list if item)
- else:
- session_summary = ""
- recent_messages = session_info.get("recent_messages") if session_info else None
+ session_summary = (
+ str(session_info.get("latest_archive_overview") or "") if session_info else ""
+ )
+ current_messages = session_info.get("current_messages") if session_info else None
query_plan: Optional[QueryPlan] = None
if primary_target_uri and primary_target_uri not in {"/", "viking://"}:
@@ -987,11 +985,11 @@ class VikingFS:
target_abstract = ""
# With session context: intent analysis
- if session_summary or recent_messages:
+ if session_summary or current_messages:
analyzer = IntentAnalyzer(max_recent_messages=5)
query_plan = await analyzer.analyze(
compression_summary=session_summary or "",
- messages=recent_messages or [],
+ messages=current_messages or [],
current_message=query,
context_type=target_context_type,
target_abstract=target_abstract,
diff --git a/openviking/sync_client.py b/openviking/sync_client.py
index bb98cf20f..b74d545ad 100644
--- a/openviking/sync_client.py
+++ b/openviking/sync_client.py
@@ -47,9 +47,9 @@ class SyncOpenViking:
"""List all sessions."""
return run_async(self._async_client.list_sessions())
- def get_session(self, session_id: str) -> Dict[str, Any]:
+ def get_session(self, session_id: str, *, auto_create: bool = False) -> Dict[str, Any]:
"""Get session details."""
- return run_async(self._async_client.get_session(session_id))
+ return run_async(self._async_client.get_session(session_id, auto_create=auto_create))
def delete_session(self, session_id: str) -> None:
"""Delete a session."""
@@ -80,6 +80,10 @@ class SyncOpenViking:
"""Commit a session (archive and extract memories)."""
return run_async(self._async_client.commit_session(session_id, telemetry=telemetry))
+ def get_task(self, task_id: str) -> Optional[Dict[str, Any]]:
+ """Query background task status."""
+ return run_async(self._async_client.get_task(task_id))
+
def add_resource(
self,
path: str,
diff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.py
index 972072d41..faeaac5a9 100644
--- a/openviking_cli/client/base.py
+++ b/openviking_cli/client/base.py
@@ -202,7 +202,7 @@ class BaseClient(ABC):
...
@abstractmethod
- async def get_session(self, session_id: str) -> Dict[str, Any]:
+ async def get_session(self, session_id: str, *, auto_create: bool = False) -> Dict[str, Any]:
"""Get session details."""
...
diff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.py
index 9383f085f..da50d4e83 100644
--- a/openviking_cli/client/http.py
+++ b/openviking_cli/client/http.py
@@ -703,9 +703,12 @@ class AsyncHTTPClient(BaseClient):
response = await self._http.get("/api/v1/sessions")
return self._handle_response(response)
- async def get_session(self, session_id: str) -> Dict[str, Any]:
+ async def get_session(self, session_id: str, *, auto_create: bool = False) -> Dict[str, Any]:
"""Get session details."""
- response = await self._http.get(f"/api/v1/sessions/{session_id}")
+ params = {}
+ if auto_create:
+ params["auto_create"] = "true"
+ response = await self._http.get(f"/api/v1/sessions/{session_id}", params=params)
return self._handle_response(response)
async def delete_session(self, session_id: str) -> None:
@@ -713,6 +716,20 @@ class AsyncHTTPClient(BaseClient):
response = await self._http.delete(f"/api/v1/sessions/{session_id}")
self._handle_response(response)
+ async def get_task(self, task_id: str) -> Optional[Dict[str, Any]]:
+ """Query background task status.
+
+ Args:
+ task_id: Task ID (returned by commit)
+
+ Returns:
+ Task info dict, or None if not found
+ """
+ response = await self._http.get(f"/api/v1/tasks/{task_id}")
+ if response.status_code == 404:
+ return None
+ return self._handle_response(response)
+
async def commit_session(
self, session_id: str, telemetry: TelemetryRequest = False
) -> Dict[str, Any]:
diff --git a/openviking_cli/client/sync_http.py b/openviking_cli/client/sync_http.py
index d87351867..a6b898a60 100644
--- a/openviking_cli/client/sync_http.py
+++ b/openviking_cli/client/sync_http.py
@@ -86,9 +86,9 @@ class SyncHTTPClient:
"""List all sessions."""
return run_async(self._async_client.list_sessions())
- def get_session(self, session_id: str) -> Dict[str, Any]:
+ def get_session(self, session_id: str, *, auto_create: bool = False) -> Dict[str, Any]:
"""Get session details."""
- return run_async(self._async_client.get_session(session_id))
+ return run_async(self._async_client.get_session(session_id, auto_create=auto_create))
def delete_session(self, session_id: str) -> None:
"""Delete a session."""
@@ -113,6 +113,10 @@ class SyncHTTPClient:
"""
return run_async(self._async_client.add_message(session_id, role, content, parts))
+ def get_task(self, task_id: str) -> Optional[Dict[str, Any]]:
+ """Query background task status."""
+ return run_async(self._async_client.get_task(task_id))
+
def commit_session(
self, session_id: str, telemetry: TelemetryRequest = False
) -> Dict[str, Any]:
diff --git a/tests/README.md b/tests/README.md
index f5e18366b..ae4186a7e 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -152,7 +152,7 @@ Tests for session management (`Session` class).
| `test_session_messages.py` | Message management | `add_message()` user/assistant roles, TextPart/ContextPart/ToolPart; `update_tool_part()` status transitions (running→completed/failed) |
| `test_session_usage.py` | Usage tracking | `used()` record context URIs, record skill usage, record both; multiple usage records per session |
| `test_session_commit.py` | Session commit | `commit()` success status, memory extraction trigger, message archiving, empty session handling, multiple commits, usage record persistence |
-| `test_session_context.py` | Context for search | `get_context_for_search()` with max_messages/max_archives limits; context after commit with archived summaries |
+| `test_session_context.py` | Context for search | `get_context_for_search()` with `current_messages` + `latest_archive_overview`; latest completed archive only |
### vectordb/
diff --git a/tests/server/test_api_sessions.py b/tests/server/test_api_sessions.py
index 368db431f..9fca12532 100644
--- a/tests/server/test_api_sessions.py
+++ b/tests/server/test_api_sessions.py
@@ -6,7 +6,6 @@
import httpx
from openviking.server.identity import RequestContext, Role
-from openviking.telemetry import get_current_telemetry
from openviking_cli.session.user_id import UserIdentifier
@@ -141,114 +140,16 @@ async def test_compress_session(client: httpx.AsyncClient):
json={"role": "user", "content": "Hello"},
)
+ # Default wait=False: returns accepted with task_id
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"] == "accepted"
assert "usage" not in body
assert "telemetry" not in body
-async def test_compress_session_with_telemetry(client: httpx.AsyncClient):
- create_resp = await client.post("/api/v1/sessions", json={})
- session_id = create_resp.json()["result"]["session_id"]
- await client.post(
- f"/api/v1/sessions/{session_id}/messages",
- json={"role": "user", "content": "Trace this commit"},
- )
-
- resp = await client.post(
- f"/api/v1/sessions/{session_id}/commit",
- json={"telemetry": True},
- )
- assert resp.status_code == 200
- body = resp.json()
- assert body["status"] == "ok"
- summary = body["telemetry"]["summary"]
- assert summary["operation"] == "session.commit"
- assert {"total", "llm", "embedding"}.issubset(summary["tokens"].keys())
- assert summary["memory"]["extracted"] is not None
- assert "extract" in summary["memory"]
- assert "semantic_nodes" not in summary
- assert "usage" not in body
-
-
-async def test_compress_session_with_telemetry_includes_memory_extract_breakdown(
- client: httpx.AsyncClient, service, monkeypatch
-):
- create_resp = await client.post("/api/v1/sessions", json={})
- session_id = create_resp.json()["result"]["session_id"]
-
- async def fake_commit_async(_session_id: str, _ctx):
- telemetry = get_current_telemetry()
- telemetry.set("memory.extracted", 2)
- telemetry.set("memory.extract.total.duration_ms", 321.5)
- telemetry.set("memory.extract.candidates.total", 4)
- telemetry.set("memory.extract.candidates.standard", 3)
- telemetry.set("memory.extract.candidates.tool_skill", 1)
- telemetry.set("memory.extract.created", 1)
- telemetry.set("memory.extract.merged", 1)
- telemetry.set("memory.extract.deleted", 0)
- telemetry.set("memory.extract.skipped", 2)
- telemetry.set("memory.extract.stage.prepare_inputs.duration_ms", 5.0)
- telemetry.set("memory.extract.stage.llm_extract.duration_ms", 200.0)
- telemetry.set("memory.extract.stage.normalize_candidates.duration_ms", 10.0)
- telemetry.set("memory.extract.stage.tool_skill_stats.duration_ms", 4.5)
- telemetry.set("memory.extract.stage.profile_create.duration_ms", 7.0)
- telemetry.set("memory.extract.stage.tool_skill_merge.duration_ms", 15.0)
- telemetry.set("memory.extract.stage.dedup.duration_ms", 55.0)
- telemetry.set("memory.extract.stage.create_memory.duration_ms", 12.0)
- telemetry.set("memory.extract.stage.merge_existing.duration_ms", 9.0)
- telemetry.set("memory.extract.stage.delete_existing.duration_ms", 0.0)
- telemetry.set("memory.extract.stage.create_relations.duration_ms", 3.0)
- telemetry.set("memory.extract.stage.flush_semantic.duration_ms", 1.0)
- return {
- "session_id": _session_id,
- "status": "committed",
- "memories_extracted": 2,
- "active_count_updated": 0,
- "archived": True,
- "stats": None,
- }
-
- monkeypatch.setattr(service.sessions, "commit_async", fake_commit_async)
-
- resp = await client.post(
- f"/api/v1/sessions/{session_id}/commit",
- json={"telemetry": True},
- )
- assert resp.status_code == 200
- body = resp.json()
- extract = body["telemetry"]["summary"]["memory"]["extract"]
- assert extract["duration_ms"] == 321.5
- assert extract["candidates"] == {"total": 4, "standard": 3, "tool_skill": 1}
- assert extract["actions"] == {"created": 1, "merged": 1, "deleted": 0, "skipped": 2}
- assert extract["stages"]["llm_extract_ms"] == 200.0
- assert extract["stages"]["flush_semantic_ms"] == 1.0
-
-
-async def test_compress_session_with_summary_only_telemetry(client: httpx.AsyncClient):
- create_resp = await client.post("/api/v1/sessions", json={})
- session_id = create_resp.json()["result"]["session_id"]
- await client.post(
- f"/api/v1/sessions/{session_id}/messages",
- json={"role": "user", "content": "Summary only telemetry"},
- )
-
- resp = await client.post(
- f"/api/v1/sessions/{session_id}/commit",
- json={"telemetry": {"summary": True}},
- )
- assert resp.status_code == 200
- body = resp.json()
- assert body["status"] == "ok"
- assert body["telemetry"]["summary"]["operation"] == "session.commit"
- assert "usage" not in body
- assert "events" not in body["telemetry"]
- assert "truncated" not in body["telemetry"]
- assert "dropped" not in body["telemetry"]
-
-
async def test_extract_session_jsonable_regression(client: httpx.AsyncClient, service, monkeypatch):
"""Regression: extract endpoint should serialize internal objects."""
diff --git a/tests/session/conftest.py b/tests/session/conftest.py
index 1395738f2..0bdaa426e 100644
--- a/tests/session/conftest.py
+++ b/tests/session/conftest.py
@@ -3,15 +3,34 @@
"""Session test fixtures"""
+import asyncio
from typing import AsyncGenerator
import pytest_asyncio
from openviking import AsyncOpenViking
from openviking.message import TextPart, ToolPart
+from openviking.service.task_tracker import TaskStatus, get_task_tracker, reset_task_tracker
from openviking.session import Session
+@pytest_asyncio.fixture(autouse=True)
+async def _drain_background_tasks(client: AsyncOpenViking):
+ """Wait for background commit tasks to finish before client teardown."""
+ reset_task_tracker()
+ yield
+ # Drain asyncio.create_task() background tasks BEFORE client.close()
+ tracker = get_task_tracker()
+ for _ in range(100): # up to 10s
+ pending = [
+ t for t in tracker.list_tasks() if t.status in (TaskStatus.PENDING, TaskStatus.RUNNING)
+ ]
+ if not pending:
+ break
+ await asyncio.sleep(0.1)
+ reset_task_tracker()
+
+
@pytest_asyncio.fixture(scope="function")
async def session(client: AsyncOpenViking) -> AsyncGenerator[Session, None]:
"""Create new Session"""
diff --git a/tests/session/memory/test_compressor_v2.py b/tests/session/memory/test_compressor_v2.py
index bd6d14846..4e4246ce4 100644
--- a/tests/session/memory/test_compressor_v2.py
+++ b/tests/session/memory/test_compressor_v2.py
@@ -6,10 +6,11 @@ Test for SessionCompressorV2.
Uses MockVikingFS and real VLM (from config).
"""
-from unittest.mock import patch
+import logging
+from types import SimpleNamespace
from typing import Any, Dict, List
+from unittest.mock import patch
-import logging
import pytest
from openviking.message import Message, TextPart
@@ -63,10 +64,7 @@ class MockVikingFS:
await self.mkdir(parent_uri)
# Write the file
- self._store[uri] = {
- "type": "file",
- "content": content
- }
+ self._store[uri] = {"type": "file", "content": content}
# Update parent directory's entries
if parent_uri and parent_uri in self._store:
@@ -76,17 +74,14 @@ class MockVikingFS:
"name": name,
"isDir": False,
"uri": uri,
- "abstract": content[:100] if content else ""
+ "abstract": content[:100] if content else "",
}
# Update or add to parent's children
parent = self._store[parent_uri]
if "children" not in parent:
parent["children"] = []
# Remove existing entry if present
- parent["children"] = [
- c for c in parent["children"]
- if c.get("name") != name
- ]
+ parent["children"] = [c for c in parent["children"] if c.get("name") != name]
parent["children"].append(file_entry)
async def ls(self, uri: str, **kwargs) -> List[Dict[str, Any]]:
@@ -107,25 +102,15 @@ class MockVikingFS:
await self.mkdir(parent_uri)
# Create this directory
- self._store[uri] = {
- "type": "dir",
- "children": []
- }
+ self._store[uri] = {"type": "dir", "children": []}
# Update parent directory's entries
if parent_uri and parent_uri in self._store:
name = self._get_name_from_uri(uri)
- dir_entry = {
- "name": name,
- "isDir": True,
- "uri": uri
- }
+ dir_entry = {"name": name, "isDir": True, "uri": uri}
parent = self._store[parent_uri]
# Remove existing entry if present
- parent["children"] = [
- c for c in parent.get("children", [])
- if c.get("name") != name
- ]
+ parent["children"] = [c for c in parent.get("children", []) if c.get("name") != name]
parent["children"].append(dir_entry)
async def rm(self, uri: str, **kwargs) -> None:
@@ -138,10 +123,7 @@ class MockVikingFS:
name = self._get_name_from_uri(uri)
if parent_uri and parent_uri in self._store:
parent = self._store[parent_uri]
- parent["children"] = [
- c for c in parent.get("children", [])
- if c.get("name") != name
- ]
+ parent["children"] = [c for c in parent.get("children", []) if c.get("name") != name]
# Remove the file/directory
del self._store[uri]
@@ -162,13 +144,10 @@ class MockVikingFS:
if entry.get("type") == "file":
name = self._get_name_from_uri(uri)
content = entry.get("content", "")
- if (query_lower in name.lower() or
- query_lower in content.lower()):
- memories.append({
- "uri": uri,
- "name": name,
- "abstract": content[:200] if content else ""
- })
+ if query_lower in name.lower() or query_lower in content.lower():
+ memories.append(
+ {"uri": uri, "name": name, "abstract": content[:200] if content else ""}
+ )
return {
"memories": memories,
@@ -209,21 +188,14 @@ class MockVikingFS:
if uri not in self._snapshot:
added[uri] = content
elif content != self._snapshot[uri]:
- modified[uri] = {
- "old": self._snapshot[uri],
- "new": content
- }
+ modified[uri] = {"old": self._snapshot[uri], "new": content}
# Check for deleted files
for uri in self._snapshot:
if uri not in current_files:
deleted[uri] = self._snapshot[uri]
- return {
- "added": added,
- "modified": modified,
- "deleted": deleted
- }
+ return {"added": added, "modified": modified, "deleted": deleted}
def create_test_conversation() -> List[Message]:
@@ -234,7 +206,11 @@ def create_test_conversation() -> List[Message]:
msg1 = Message(
id="msg1",
role="user",
- parts=[TextPart("We're starting the memory extraction feature for the OpenViking project today. This project is an Agent-native context database.")],
+ parts=[
+ TextPart(
+ "We're starting the memory extraction feature for the OpenViking project today. This project is an Agent-native context database."
+ )
+ ],
)
messages.append(msg1)
@@ -242,7 +218,11 @@ def create_test_conversation() -> List[Message]:
msg2 = Message(
id="msg2",
role="assistant",
- parts=[TextPart("Great! The memory extraction feature is important. What technical approach are we planning to use?")],
+ parts=[
+ TextPart(
+ "Great! The memory extraction feature is important. What technical approach are we planning to use?"
+ )
+ ],
)
messages.append(msg2)
@@ -250,10 +230,12 @@ def create_test_conversation() -> List[Message]:
msg3 = Message(
id="msg3",
role="user",
- parts=[TextPart(
- "We've decided to use the MemoryReAct pattern, combined with LLMs to analyze conversations and generate memory operations. "
- "There are two main memory types: cards for knowledge cards (Zettelkasten note-taking method), and events for recording important events and decisions."
- )],
+ parts=[
+ TextPart(
+ "We've decided to use the MemoryReAct pattern, combined with LLMs to analyze conversations and generate memory operations. "
+ "There are two main memory types: cards for knowledge cards (Zettelkasten note-taking method), and events for recording important events and decisions."
+ )
+ ],
)
messages.append(msg3)
@@ -269,10 +251,12 @@ def create_test_conversation() -> List[Message]:
msg5 = Message(
id="msg5",
role="user",
- parts=[TextPart(
- "Cards are stored in viking://agent/{agent_space}/memories/cards, each card has name and content fields. "
- "Events are stored in viking://user/{user_space}/memories/events, each event has event_name, event_time, and content fields."
- )],
+ parts=[
+ TextPart(
+ "Cards are stored in viking://agent/{agent_space}/memories/cards, each card has name and content fields. "
+ "Events are stored in viking://user/{user_space}/memories/events, each event has event_name, event_time, and content fields."
+ )
+ ],
)
messages.append(msg5)
@@ -282,6 +266,55 @@ def create_test_conversation() -> List[Message]:
class TestCompressorV2:
"""Tests for SessionCompressorV2."""
+ @pytest.mark.asyncio
+ async def test_extract_long_term_memories_includes_latest_archive_overview(self):
+ """Latest archive overview should be prepended to the v2 conversation context."""
+ compressor = SessionCompressorV2(vikingdb=None)
+ user = UserIdentifier.the_default_user()
+ ctx = RequestContext(user=user, role=Role.ROOT)
+ messages = [Message.create_user("Current task")]
+ captured: dict[str, str] = {}
+
+ class DummyOrchestrator:
+ registry = object()
+
+ async def run(self, conversation: str):
+ captured["conversation"] = conversation
+ return (
+ SimpleNamespace(
+ write_uris=[],
+ edit_uris=[],
+ edit_overview_uris=[],
+ delete_uris=[],
+ ),
+ [],
+ )
+
+ class DummyUpdater:
+ async def apply_operations(self, operations, ctx, registry=None):
+ return SimpleNamespace(
+ written_uris=[],
+ edited_uris=[],
+ deleted_uris=[],
+ errors=[],
+ )
+
+ compressor._get_or_create_react = lambda ctx=None: DummyOrchestrator()
+ compressor._get_or_create_updater = lambda: DummyUpdater()
+
+ result = await compressor.extract_long_term_memories(
+ messages=messages,
+ user=user,
+ session_id="test-session-v2",
+ ctx=ctx,
+ latest_archive_overview="LATEST OVERVIEW",
+ )
+
+ assert result == []
+ assert "## Previous Archive Overview" in captured["conversation"]
+ assert "LATEST OVERVIEW" in captured["conversation"]
+ assert "[user]: Current task" in captured["conversation"]
+
@pytest.mark.integration
@pytest.mark.asyncio
async def test_extract_long_term_memories(self):
@@ -333,9 +366,13 @@ class TestCompressorV2:
# Patch get_viking_fs() to return our mock
# Need to patch it in all the places it's used
- with patch('openviking.session.memory.memory_react.get_viking_fs', return_value=viking_fs):
- with patch('openviking.session.memory.memory_updater.get_viking_fs', return_value=viking_fs):
- with patch('openviking.session.compressor_v2.get_viking_fs', return_value=viking_fs):
+ with patch("openviking.session.memory.memory_react.get_viking_fs", return_value=viking_fs):
+ with patch(
+ "openviking.session.memory.memory_updater.get_viking_fs", return_value=viking_fs
+ ):
+ with patch(
+ "openviking.session.compressor_v2.get_viking_fs", return_value=viking_fs
+ ):
# Actually call extract_long_term_memories()
logger.info("Calling SessionCompressorV2.extract_long_term_memories()...")
memories = await compressor.extract_long_term_memories(
@@ -351,12 +388,12 @@ class TestCompressorV2:
print("TEST RESULTS")
print("=" * 80)
print(f"Returned memories list length: {len(memories)}")
- print(f"Note: v2 returns empty list because it writes directly to storage")
+ print("Note: v2 returns empty list because it writes directly to storage")
print("=" * 80)
# Check what changed
diff = viking_fs.diff_since_snapshot()
- print(f"\nChanges detected:")
+ print("\nChanges detected:")
print(f" Added: {len(diff['added'])} files")
print(f" Modified: {len(diff['modified'])} files")
print(f" Deleted: {len(diff['deleted'])} files")
diff --git a/tests/session/test_session_commit.py b/tests/session/test_session_commit.py
index efa57fc70..ed1fddbd2 100644
--- a/tests/session/test_session_commit.py
+++ b/tests/session/test_session_commit.py
@@ -3,30 +3,50 @@
"""Commit tests"""
+import asyncio
+
from openviking import AsyncOpenViking
from openviking.message import TextPart
+from openviking.service.task_tracker import get_task_tracker
from openviking.session import Session
+async def _wait_for_task(task_id: str, timeout: float = 30.0) -> dict:
+ """Poll the task tracker until the task reaches a terminal state."""
+ tracker = get_task_tracker()
+ for _ in range(int(timeout / 0.1)):
+ task = tracker.get(task_id)
+ if task and task.status.value in ("completed", "failed"):
+ return task.to_dict()
+ await asyncio.sleep(0.1)
+ raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")
+
+
class TestCommit:
"""Test commit"""
async def test_commit_success(self, session_with_messages: Session):
- """Test successful commit"""
- result = session_with_messages.commit()
+ """Test successful commit returns accepted with task_id"""
+ result = await session_with_messages.commit_async()
assert isinstance(result, dict)
- assert result.get("status") == "committed"
+ assert result.get("status") == "accepted"
assert "session_id" in result
+ assert result.get("task_id") is not None
async def test_commit_extracts_memories(
self, session_with_messages: Session, client: AsyncOpenViking
):
- """Test commit extracts memories"""
- result = session_with_messages.commit()
+ """Test commit kicks off background memory extraction"""
+ result = await session_with_messages.commit_async()
+ task_id = result["task_id"]
- assert "memories_extracted" in result
- # Wait for memory extraction to complete
+ # Wait for background memory extraction to complete
+ task_result = await _wait_for_task(task_id)
+ assert task_result["status"] == "completed"
+ assert "memories_extracted" in task_result["result"]
+
+ # Wait for semantic/embedding queues
await client.wait_processed(timeout=60.0)
async def test_commit_archives_messages(self, session_with_messages: Session):
@@ -34,7 +54,7 @@ class TestCommit:
initial_message_count = len(session_with_messages.messages)
assert initial_message_count > 0
- result = session_with_messages.commit()
+ result = await session_with_messages.commit_async()
assert result.get("archived") is True
# Current message list should be cleared after commit
@@ -43,9 +63,10 @@ class TestCommit:
async def test_commit_empty_session(self, session: Session):
"""Test committing empty session"""
# Empty session commit should not raise error
- result = session.commit()
+ result = await session.commit_async()
assert isinstance(result, dict)
+ assert result.get("archived") is False
async def test_commit_multiple_times(self, client: AsyncOpenViking):
"""Test multiple commits"""
@@ -54,14 +75,60 @@ class TestCommit:
# First round of conversation
session.add_message("user", [TextPart("First round message")])
session.add_message("assistant", [TextPart("First round response")])
- result1 = session.commit()
- assert result1.get("status") == "committed"
+ result1 = await session.commit_async()
+ assert result1.get("status") == "accepted"
+ assert result1.get("task_id") is not None
+
+ # Wait for first commit's background task to finish
+ await _wait_for_task(result1["task_id"])
# Second round of conversation
session.add_message("user", [TextPart("Second round message")])
session.add_message("assistant", [TextPart("Second round response")])
- result2 = session.commit()
- assert result2.get("status") == "committed"
+ result2 = await session.commit_async()
+ assert result2.get("status") == "accepted"
+ assert result2.get("task_id") is not None
+
+ async def test_commit_uses_latest_archive_overview_for_summary_and_extraction(
+ self, client: AsyncOpenViking
+ ):
+ """Second commit should pass the latest completed archive overview into Phase 2."""
+ session = client.session(session_id="latest_overview_threading_test")
+
+ session.add_message("user", [TextPart("First round message")])
+ session.add_message("assistant", [TextPart("First round response")])
+ result1 = await session.commit_async()
+ await _wait_for_task(result1["task_id"])
+
+ previous_overview = await session._viking_fs.read_file(
+ f"{result1['archive_uri']}/.overview.md",
+ ctx=session.ctx,
+ )
+ seen: dict[str, str] = {}
+
+ original_generate = session._generate_archive_summary_async
+
+ async def capture_generate(messages, latest_archive_overview=""):
+ seen["summary"] = latest_archive_overview
+ return await original_generate(
+ messages, latest_archive_overview=latest_archive_overview
+ )
+
+ async def capture_extract(*args, **kwargs):
+ seen["extract"] = kwargs.get("latest_archive_overview", "")
+ return []
+
+ session._generate_archive_summary_async = capture_generate
+ session._session_compressor.extract_long_term_memories = capture_extract
+
+ session.add_message("user", [TextPart("Second round message")])
+ session.add_message("assistant", [TextPart("Second round response")])
+ result2 = await session.commit_async()
+ task_result = await _wait_for_task(result2["task_id"])
+
+ assert task_result["status"] == "completed"
+ assert seen["summary"] == previous_overview
+ assert seen["extract"] == previous_overview
async def test_commit_with_usage_records(self, client: AsyncOpenViking):
"""Test commit with usage records"""
@@ -71,10 +138,14 @@ class TestCommit:
session.used(contexts=["viking://user/test/resources/doc.md"])
session.add_message("assistant", [TextPart("Response")])
- result = session.commit()
+ result = await session.commit_async()
+
+ assert result.get("status") == "accepted"
+ assert result.get("task_id") is not None
- assert result.get("status") == "committed"
- assert "active_count_updated" in result
+ # active_count_updated is now in the background task result
+ task_result = await _wait_for_task(result["task_id"])
+ assert task_result["status"] == "completed"
async def test_active_count_incremented_after_commit(self, client_with_resource_sync: tuple):
"""Regression test: active_count must actually increment after commit.
@@ -112,9 +183,12 @@ class TestCommit:
session.add_message("user", [TextPart("Query")])
session.used(contexts=[uri])
session.add_message("assistant", [TextPart("Answer")])
- result = session.commit()
+ result = await session.commit_async()
- assert result.get("active_count_updated") == 1
+ # Wait for background task to complete (active_count is updated there)
+ task_result = await _wait_for_task(result["task_id"])
+ assert task_result["status"] == "completed"
+ assert task_result["result"]["active_count_updated"] == 1
# Verify the count actually changed in storage
records_after = await vikingdb.get_context_by_uri(
diff --git a/tests/session/test_session_commit_race.py b/tests/session/test_session_commit_race.py
index e71a471f7..0583644f5 100644
--- a/tests/session/test_session_commit_race.py
+++ b/tests/session/test_session_commit_race.py
@@ -41,12 +41,15 @@ class TestCommitRace:
phase1_done = asyncio.Event()
original_generate = session._generate_archive_summary_async
- async def slow_generate(messages):
+ async def slow_generate(messages, latest_archive_overview=""):
# Signal that Phase 1 is complete (lock released, messages cleared)
phase1_done.set()
# Yield control so add_message can run before archive completes
await asyncio.sleep(0)
- return await original_generate(messages)
+ return await original_generate(
+ messages,
+ latest_archive_overview=latest_archive_overview,
+ )
session._generate_archive_summary_async = slow_generate
diff --git a/tests/session/test_session_context.py b/tests/session/test_session_context.py
index 593326380..8eeacd6f9 100644
--- a/tests/session/test_session_context.py
+++ b/tests/session/test_session_context.py
@@ -3,11 +3,24 @@
"""Context retrieval tests"""
+import asyncio
+
from openviking import AsyncOpenViking
from openviking.message import TextPart
+from openviking.service.task_tracker import get_task_tracker
from openviking.session import Session
+async def _wait_for_task(task_id: str, timeout: float = 30.0) -> dict:
+ tracker = get_task_tracker()
+ for _ in range(int(timeout / 0.1)):
+ task = tracker.get(task_id)
+ if task and task.status.value in ("completed", "failed"):
+ return task.to_dict()
+ await asyncio.sleep(0.1)
+ raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")
+
+
class TestGetContextForSearch:
"""Test get_context_for_search"""
@@ -16,37 +29,72 @@ class TestGetContextForSearch:
context = await session_with_messages.get_context_for_search(query="testing help")
assert isinstance(context, dict)
- assert "summaries" in context or "recent_messages" in context
+ assert "latest_archive_overview" in context
+ assert "current_messages" in context
async def test_get_context_with_max_messages(self, session_with_messages: Session):
"""Test limiting max messages"""
context = await session_with_messages.get_context_for_search(query="test", max_messages=2)
assert isinstance(context, dict)
- if "recent_messages" in context:
- assert len(context["recent_messages"]) <= 2
+ assert len(context["current_messages"]) <= 2
- async def test_get_context_with_max_archives(self, client: AsyncOpenViking):
- """Test limiting max archives"""
+ async def test_get_context_returns_latest_completed_archive_only(self, client: AsyncOpenViking):
+ """Current context should expose only the latest completed archive overview."""
session = client.session(session_id="archive_context_test")
- # Add messages and commit (create archive)
session.add_message("user", [TextPart("First message")])
session.add_message("assistant", [TextPart("First response")])
- session.commit()
+ result1 = await session.commit_async()
+ await _wait_for_task(result1["task_id"])
- # Add more messages
session.add_message("user", [TextPart("Second message")])
-
- context = await session.get_context_for_search(query="test", max_archives=1)
+ session.add_message("assistant", [TextPart("Second response")])
+ session.add_message("user", [TextPart("Third message")])
+ result2 = await session.commit_async()
+ await _wait_for_task(result2["task_id"])
+ latest_overview = await session._viking_fs.read_file(
+ f"{result2['archive_uri']}/.overview.md",
+ ctx=session.ctx,
+ )
+
+ session.add_message("user", [TextPart("Current message")])
+ context = await session.get_context_for_search(query="test")
assert isinstance(context, dict)
+ assert context["latest_archive_overview"] == latest_overview
+ assert len(context["current_messages"]) == 1
+
+ async def test_get_context_skips_incomplete_latest_archive(self, client: AsyncOpenViking):
+ """Incomplete archives without .done must not replace the latest completed overview."""
+ session = client.session(session_id="archive_context_incomplete_test")
+
+ session.add_message("user", [TextPart("First message")])
+ session.add_message("assistant", [TextPart("First response")])
+ result = await session.commit_async()
+ await _wait_for_task(result["task_id"])
+
+ completed_overview = await session._viking_fs.read_file(
+ f"{result['archive_uri']}/.overview.md",
+ ctx=session.ctx,
+ )
+ await session._viking_fs.write_file(
+ uri=f"{session.uri}/history/archive_999/.overview.md",
+ content="INCOMPLETE OVERVIEW",
+ ctx=session.ctx,
+ )
+
+ context = await session.get_context_for_search(query="test")
+
+ assert context["latest_archive_overview"] == completed_overview
async def test_get_context_empty_session(self, session: Session):
"""Test getting context from empty session"""
context = await session.get_context_for_search(query="test")
assert isinstance(context, dict)
+ assert context["latest_archive_overview"] == ""
+ assert context["current_messages"] == []
async def test_get_context_after_commit(self, client: AsyncOpenViking):
"""Test getting context after commit"""
@@ -57,7 +105,8 @@ class TestGetContextForSearch:
session.add_message("assistant", [TextPart("Response before commit")])
# Commit
- session.commit()
+ result = await session.commit_async()
+ await _wait_for_task(result["task_id"])
# Add new messages
session.add_message("user", [TextPart("New message after commit")])
@@ -66,3 +115,5 @@ class TestGetContextForSearch:
context = await session.get_context_for_search(query="test")
assert isinstance(context, dict)
+ assert context["latest_archive_overview"]
+ assert len(context["current_messages"]) == 1
diff --git a/tests/test_session_async_commit.py b/tests/test_session_async_commit.py
index 4de752eb8..ea08a1018 100644
--- a/tests/test_session_async_commit.py
+++ b/tests/test_session_async_commit.py
@@ -4,7 +4,6 @@
"""Tests for async session commit support."""
import asyncio
-import time
from typing import AsyncGenerator, Tuple
import httpx
@@ -16,11 +15,13 @@ 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
+from openviking.service.task_tracker import TaskStatus, get_task_tracker, reset_task_tracker
@pytest_asyncio.fixture
async def api_client(temp_dir) -> AsyncGenerator[Tuple[httpx.AsyncClient, OpenVikingService], None]:
"""Create in-process HTTP client for API endpoint tests."""
+ reset_task_tracker()
service = OpenVikingService(path=str(temp_dir / "api_data"))
await service.initialize()
app = create_app(config=ServerConfig(), service=service)
@@ -32,16 +33,19 @@ async def api_client(temp_dir) -> AsyncGenerator[Tuple[httpx.AsyncClient, OpenVi
await service.close()
await AsyncOpenViking.reset()
+ reset_task_tracker()
@pytest_asyncio.fixture
async def ov_client(temp_dir) -> AsyncGenerator[AsyncOpenViking, None]:
"""Create AsyncOpenViking client for unit tests."""
+ reset_task_tracker()
client = AsyncOpenViking(path=str(temp_dir / "ov_data"))
await client.initialize()
yield client
await client.close()
await AsyncOpenViking.reset()
+ reset_task_tracker()
async def _new_session_with_one_message(client: httpx.AsyncClient) -> str:
@@ -57,84 +61,38 @@ async def _new_session_with_one_message(client: httpx.AsyncClient) -> str:
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."""
+async def test_commit_async_returns_accepted_with_task_id(ov_client: AsyncOpenViking):
+ """commit_async should return status=accepted with a task_id."""
session = ov_client.session(session_id="async-shape-test")
session.add_message("user", [TextPart("first")])
- sync_result = session.commit()
+ result = await session.commit_async()
- session.add_message("user", [TextPart("second")])
- async_result = await session.commit_async()
+ assert result["status"] == "accepted"
+ assert result["task_id"] is not None
+ assert result["archived"] is True
+ assert "session_id" in result
+ assert "archive_uri" in result
- 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."""
+async def test_commit_endpoint_returns_accepted_with_task_id(api_client):
+ """Commit endpoint should return status=accepted with a task_id."""
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
+ 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"] == "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"
+ assert "task_id" in body["result"]
+
+ # Wait for background task to finish
+ task_id = body["result"]["task_id"]
+ if task_id:
+ tracker = get_task_tracker()
+ for _ in range(300):
+ task = tracker.get(task_id)
+ if task and task.status in (TaskStatus.COMPLETED, TaskStatus.FAILED):
+ break
+ await asyncio.sleep(0.1)
diff --git a/tests/test_session_task_tracking.py b/tests/test_session_task_tracking.py
index 1306d5003..270afd011 100644
--- a/tests/test_session_task_tracking.py
+++ b/tests/test_session_task_tracking.py
@@ -14,7 +14,7 @@ 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
-from openviking.service.task_tracker import reset_task_tracker
+from openviking.service.task_tracker import get_task_tracker, reset_task_tracker
@pytest_asyncio.fixture
@@ -46,64 +46,86 @@ async def _new_session_with_message(client: httpx.AsyncClient) -> str:
return session_id
-# ── wait=false returns task_id ──
-
-
-async def test_commit_wait_false_returns_task_id(api_client):
- """wait=false should return a task_id for polling."""
+# ── Helper: create a mock commit that properly tracks tasks ──
+
+
+def _make_tracked_commit(behavior="instant", result_overrides=None, gate=None, started=None):
+ """Create a mock commit_async that creates & manages a tracked task.
+
+ The mock mirrors the real Session.commit_async() contract: it creates a
+ TaskRecord, launches a background asyncio task, and returns immediately
+ with {status: "accepted", task_id: ...}.
+
+ Args:
+ behavior: "instant" (complete immediately) | "gated" (wait on gate) | "fail" (raise)
+ result_overrides: dict merged into task.result on completion, or
+ {"error": "..."} for fail behavior
+ gate: asyncio.Event to await before completing (for "gated")
+ started: asyncio.Event to set when background task starts (for "gated")
+ """
+
+ async def mock_commit(_sid, _ctx):
+ tracker = get_task_tracker()
+ task = tracker.create("session_commit", resource_id=_sid)
+ archive_uri = f"viking://session/test/{_sid}/history/archive_001"
+
+ async def _background():
+ tracker.start(task.task_id)
+ try:
+ if started:
+ started.set()
+ if behavior == "gated" and gate:
+ await gate.wait()
+ if behavior == "fail":
+ error_msg = (
+ result_overrides.get("error", "mock error")
+ if result_overrides
+ else "mock error"
+ )
+ raise RuntimeError(error_msg)
+ final_result = {
+ "session_id": _sid,
+ "archive_uri": archive_uri,
+ "memories_extracted": 0,
+ "active_count_updated": 0,
+ }
+ if result_overrides:
+ final_result.update(result_overrides)
+ tracker.complete(task.task_id, final_result)
+ except Exception as e:
+ tracker.fail(task.task_id, str(e))
+
+ asyncio.create_task(_background())
+
+ return {
+ "session_id": _sid,
+ "status": "accepted",
+ "task_id": task.task_id,
+ "archive_uri": archive_uri,
+ "archived": True,
+ }
+
+ return mock_commit
+
+
+# ── Commit returns task_id ──
+
+
+async def test_commit_returns_task_id(api_client):
+ """Commit should return a task_id for polling."""
client, service = api_client
session_id = await _new_session_with_message(client)
- done = asyncio.Event()
-
- async def fake_commit(_sid, _ctx):
- await asyncio.sleep(0.1)
- done.set()
- return {"session_id": _sid, "status": "committed", "memories_extracted": 0}
-
- service.sessions.commit_async = fake_commit
+ service.sessions.commit_async = _make_tracked_commit()
- resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit")
assert resp.status_code == 200
body = resp.json()
assert body["result"]["status"] == "accepted"
assert "task_id" in body["result"]
- await asyncio.wait_for(done.wait(), timeout=2.0)
-
-
-async def test_commit_wait_false_rejects_full_telemetry(api_client):
- """wait=false should reject telemetry payload requests."""
- client, _ = api_client
- session_id = await _new_session_with_message(client)
-
- resp = await client.post(
- f"/api/v1/sessions/{session_id}/commit",
- params={"wait": False},
- json={"telemetry": True},
- )
- assert resp.status_code == 400
- body = resp.json()
- assert body["status"] == "error"
- assert body["error"]["code"] == "INVALID_ARGUMENT"
- assert "wait=false" in body["error"]["message"]
-
-
-async def test_commit_wait_false_rejects_summary_only_telemetry(api_client):
- """wait=false should also reject summary-only telemetry requests."""
- client, _ = api_client
- session_id = await _new_session_with_message(client)
-
- resp = await client.post(
- f"/api/v1/sessions/{session_id}/commit",
- params={"wait": False},
- json={"telemetry": {"summary": True}},
- )
- assert resp.status_code == 400
- body = resp.json()
- assert body["status"] == "error"
- assert body["error"]["code"] == "INVALID_ARGUMENT"
- assert "wait=false" in body["error"]["message"]
+ # Let background task complete
+ await asyncio.sleep(0.2)
# ── Task lifecycle: pending → running → completed ──
@@ -117,15 +139,15 @@ async def test_task_lifecycle_success(api_client):
commit_started = asyncio.Event()
commit_gate = asyncio.Event()
- async def gated_commit(_sid, _ctx):
- commit_started.set()
- await commit_gate.wait()
- return {"session_id": _sid, "status": "committed", "memories_extracted": 5}
-
- service.sessions.commit_async = gated_commit
+ service.sessions.commit_async = _make_tracked_commit(
+ behavior="gated",
+ result_overrides={"memories_extracted": 5},
+ gate=commit_gate,
+ started=commit_started,
+ )
# Fire background commit
- resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit")
task_id = resp.json()["result"]["task_id"]
# Wait for commit to start
@@ -156,12 +178,12 @@ async def test_task_lifecycle_failure(api_client):
client, service = api_client
session_id = await _new_session_with_message(client)
- async def failing_commit(_sid, _ctx):
- raise RuntimeError("LLM provider timeout")
-
- service.sessions.commit_async = failing_commit
+ service.sessions.commit_async = _make_tracked_commit(
+ behavior="fail",
+ result_overrides={"error": "LLM provider timeout"},
+ )
- resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit")
task_id = resp.json()["result"]["task_id"]
await asyncio.sleep(0.2)
@@ -183,7 +205,7 @@ async def test_task_failed_when_memory_extraction_raises(api_client):
service.sessions._session_compressor.extractor.extract = failing_extract
- resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit")
task_id = resp.json()["result"]["task_id"]
result = None
@@ -196,7 +218,6 @@ async def test_task_failed_when_memory_extraction_raises(api_client):
break
assert result is not None
- assert result["status"] in {"completed", "failed"}
assert result["status"] == "failed"
assert "memory_extraction_failed" in result["error"]
@@ -211,47 +232,14 @@ async def test_duplicate_commit_rejected(api_client):
gate = asyncio.Event()
- async def slow_commit(_sid, _ctx):
- await gate.wait()
- return {"session_id": _sid, "status": "committed", "memories_extracted": 0}
-
- service.sessions.commit_async = slow_commit
+ service.sessions.commit_async = _make_tracked_commit(behavior="gated", gate=gate)
# First commit
- resp1 = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ resp1 = await client.post(f"/api/v1/sessions/{session_id}/commit")
assert resp1.json()["result"]["status"] == "accepted"
# Second commit should be rejected
- resp2 = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
- assert resp2.json()["status"] == "error"
- assert "already has a commit in progress" in resp2.json()["error"]["message"]
-
- gate.set()
- await asyncio.sleep(0.1)
-
-
-async def test_wait_true_rejected_while_background_commit_running(api_client):
- """wait=true must also reject duplicate commits for the same session."""
- client, service = api_client
- session_id = await _new_session_with_message(client)
-
- gate = asyncio.Event()
-
- async def slow_commit(_sid, _ctx):
- await gate.wait()
- return {"session_id": _sid, "status": "committed", "memories_extracted": 0}
-
- service.sessions.commit_async = slow_commit
-
- resp1 = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
- assert resp1.json()["result"]["status"] == "accepted"
-
- resp2 = await client.post(
- f"/api/v1/sessions/{session_id}/commit",
- params={"wait": True},
- json={"telemetry": True},
- )
- assert resp2.status_code == 200
+ resp2 = await client.post(f"/api/v1/sessions/{session_id}/commit")
assert resp2.json()["status"] == "error"
assert "already has a commit in progress" in resp2.json()["error"]["message"]
@@ -275,13 +263,10 @@ async def test_list_tasks(api_client):
client, service = api_client
session_id = await _new_session_with_message(client)
- async def instant_commit(_sid, _ctx):
- return {"session_id": _sid, "status": "committed", "memories_extracted": 0}
-
- service.sessions.commit_async = instant_commit
+ service.sessions.commit_async = _make_tracked_commit()
- await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
- await asyncio.sleep(0.1)
+ await client.post(f"/api/v1/sessions/{session_id}/commit")
+ await asyncio.sleep(0.2)
resp = await client.get("/api/v1/tasks", params={"task_type": "session_commit"})
assert resp.status_code == 200
@@ -293,14 +278,11 @@ async def test_list_tasks(api_client):
async def test_list_tasks_filter_status(api_client):
client, service = api_client
- async def instant_commit(_sid, _ctx):
- return {"session_id": _sid, "status": "committed", "memories_extracted": 0}
-
- service.sessions.commit_async = instant_commit
+ service.sessions.commit_async = _make_tracked_commit()
session_id = await _new_session_with_message(client)
- await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
- await asyncio.sleep(0.1)
+ await client.post(f"/api/v1/sessions/{session_id}/commit")
+ await asyncio.sleep(0.2)
# completed tasks
resp = await client.get("/api/v1/tasks", params={"status": "completed"})
@@ -309,26 +291,6 @@ async def test_list_tasks_filter_status(api_client):
assert t["status"] == "completed"
-# ── wait=true still works (backward compat) ──
-
-
-async def test_wait_true_still_works(api_client):
- """wait=true should return inline result, no task_id."""
- client, service = api_client
- session_id = await _new_session_with_message(client)
-
- async def instant_commit(_sid, _ctx):
- return {"session_id": _sid, "status": "committed", "memories_extracted": 2}
-
- service.sessions.commit_async = instant_commit
-
- resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": True})
- assert resp.status_code == 200
- body = resp.json()
- assert body["result"]["status"] == "committed"
- assert "task_id" not in body["result"]
-
-
# ── Error sanitization in task ──
@@ -337,12 +299,12 @@ async def test_error_sanitized_in_task(api_client):
client, service = api_client
session_id = await _new_session_with_message(client)
- async def leaky_commit(_sid, _ctx):
- raise RuntimeError("Auth failed with key sk-ant-api03-DAqSsuperSecretKey123")
-
- service.sessions.commit_async = leaky_commit
+ service.sessions.commit_async = _make_tracked_commit(
+ behavior="fail",
+ result_overrides={"error": "Auth failed with key sk-ant-api03-DAqSsuperSecretKey123"},
+ )
- resp = await client.post(f"/api/v1/sessions/{session_id}/commit", params={"wait": False})
+ resp = await client.post(f"/api/v1/sessions/{session_id}/commit")
task_id = resp.json()["result"]["task_id"]
await asyncio.sleep(0.2)