Skip to content

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

docs(transaction): align crash-recovery guidance with the 30-minute lock expiry (#3338)

Evo0d2c1516a2f9
diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.md
index b9e4bce1a..4a60190f5 100644
--- a/docs/en/concepts/09-transaction.md
+++ b/docs/en/concepts/09-transaction.md
@@ -361,7 +361,7 @@ for conflicts first:
### Lock Expiry Cleanup
-**Stale lock detection**: PathLockEngine checks the fencing token timestamp. Locks older than `lock_expire` (default 300s) are considered stale and are removed automatically during acquisition.
+**Stale lock detection**: PathLockEngine checks the fencing token timestamp. Locks older than `lock_expire` (default 1800s / 30 minutes) are considered stale and are removed automatically during acquisition.
**In-process cleanup**: LockManager checks active LockHandles every 60 seconds. Handles that still own lock files but have been inactive for longer than `lock_expire` are force-released.
@@ -374,7 +374,7 @@ for conflicts first:
| Scenario | Recovery action |
|----------|----------------|
| session_memory extraction crash | Redo memory extraction + write + enqueue from archive |
-| Crash while holding lock | Lock file remains in AGFS; stale detection auto-cleans on next acquisition (default 300s expiry) |
+| Crash while holding lock | Lock file remains in AGFS; stale detection auto-cleans on next acquisition (default 1800s / 30-minute expiry) |
| Crash after enqueue, before worker processes | QueueFS SQLite persistence; worker auto-pulls after restart |
| Orphan index | Cleaned on L2 on-demand load |
@@ -397,7 +397,7 @@ Path locks are enabled by default with no extra configuration needed. **The defa
"storage": {
"transaction": {
"lock_timeout": 5.0,
- "lock_expire": 300.0
+ "lock_expire": 1800.0
}
}
}
@@ -406,7 +406,7 @@ Path locks are enabled by default with no extra configuration needed. **The defa
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `lock_timeout` | float | Lock acquisition timeout (seconds). `0` = fail immediately if locked (default). `> 0` = wait/retry up to this many seconds. | `0.0` |
-| `lock_expire` | float | Lock inactivity threshold (seconds). Locks not refreshed within this window are treated as stale and reclaimed. | `300.0` |
+| `lock_expire` | float | Lock inactivity threshold (seconds). Locks not refreshed within this window are treated as stale and reclaimed. | `1800.0` |
### QueueFS Persistence
diff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.md
index d00ca3c86..b22f72245 100644
--- a/docs/zh/concepts/09-transaction.md
+++ b/docs/zh/concepts/09-transaction.md
@@ -370,7 +370,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
### 锁过期清理
-**陈旧锁检测**:PathLockEngine 检查 fencing token 中的时间戳。超过 `lock_expire`(默认 300s)的锁被视为陈旧锁,在加锁过程中自动移除。
+**陈旧锁检测**:PathLockEngine 检查 fencing token 中的时间戳。超过 `lock_expire`(默认 1800s / 30 分钟)的锁被视为陈旧锁,在加锁过程中自动移除。
**进程内清理**:LockManager 每 60 秒检查活跃的 LockHandle。仍持有锁文件且失活时间超过 `lock_expire` 的 handle 会被强制释放。
@@ -383,7 +383,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
| 场景 | 恢复方式 |
|------|---------|
| session_memory 提取中途崩溃 | 从 archive 重做记忆提取 + 写入 + enqueue |
-| 锁持有期间崩溃 | 锁文件留在 AGFS,下次获取时 stale 检测自动清理(默认 300s 过期)|
+| 锁持有期间崩溃 | 锁文件留在 AGFS,下次获取时 stale 检测自动清理(默认 1800s / 30 分钟过期)|
| enqueue 后 worker 处理前崩溃 | QueueFS SQLite 持久化,worker 重启后自动拉取 |
| 孤儿索引 | L2 按需加载时清理 |
@@ -406,7 +406,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
"storage": {
"transaction": {
"lock_timeout": 5.0,
- "lock_expire": 300.0
+ "lock_expire": 1800.0
}
}
}
@@ -415,7 +415,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `lock_timeout` | float | 获取锁的等待超时(秒)。`0` = 立即失败(默认);`> 0` = 最多等待此时间 | `0.0` |
-| `lock_expire` | float | 锁失活阈值(秒),超过此时间未被 refresh 的锁会被视为陈旧锁并回收 | `300.0` |
+| `lock_expire` | float | 锁失活阈值(秒),超过此时间未被 refresh 的锁会被视为陈旧锁并回收 | `1800.0` |
### QueueFS 持久化