Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(store): start writer transactions IMMEDIATE so busy_timeout applies

Djalma Júniora2da609908a0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc9f766f..0bee3729 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -140,6 +140,9 @@ version in [`docs/changelog/`](docs/changelog/):
punctuation, literal URL delimiters, or Unicode remain readable, clickable
links in exports and newly generated migration indexes.
([#1438](https://github.com/akitaonrails/ai-memory/pull/1438))
+- Made the SQLite writer wait out the 5-second busy timeout when another
+ process holds the database, such as an external `wal_checkpoint`, instead
+ of failing hook ingestion at once with "database is locked".
## [3.1.1] - 2026-10-17
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index ec94a5c1..be306b28 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -12,7 +12,7 @@
use std::os::unix::fs::{DirBuilderExt as _, OpenOptionsExt as _};
use std::path::{Path, PathBuf};
-use rusqlite::Connection;
+use rusqlite::{Connection, TransactionBehavior};
mod api_credentials;
mod auto_improve;
@@ -170,6 +170,14 @@ impl Store {
conn.pragma_update(None, "journal_size_limit", WAL_JOURNAL_SIZE_LIMIT_BYTES)?;
conn.pragma_update(None, "synchronous", "NORMAL")?;
conn.pragma_update(None, "busy_timeout", 5_000)?; // ms
+ // Writer transactions start IMMEDIATE: a deferred transaction that
+ // has already read cannot wait through the busy handler when it
+ // upgrades to write, so another process holding the write lock (an
+ // external `wal_checkpoint(TRUNCATE)`, a sqlite3 shell) failed hook
+ // admission at once with "database is locked". IMMEDIATE takes the
+ // lock at BEGIN, where `busy_timeout` applies. Refinery's
+ // per-migration transactions below inherit it unchanged otherwise.
+ conn.set_transaction_behavior(TransactionBehavior::Immediate);
// SQLite cannot disable FK enforcement inside refinery's per-migration
// transaction. Keep it off while migrations rebuild tables, then enable
diff --git a/crates/ai-memory-store/tests/suite/mod.rs b/crates/ai-memory-store/tests/suite/mod.rs
index 54fef78e..0575128a 100644
--- a/crates/ai-memory-store/tests/suite/mod.rs
+++ b/crates/ai-memory-store/tests/suite/mod.rs
@@ -35,3 +35,4 @@ mod slot_visibility;
mod stress_writer_throughput;
mod wal_bounds;
mod workstream_provenance;
+mod writer_immediate;
diff --git a/crates/ai-memory-store/tests/suite/writer_immediate.rs b/crates/ai-memory-store/tests/suite/writer_immediate.rs
new file mode 100644
index 00000000..abf866ac
--- /dev/null
+++ b/crates/ai-memory-store/tests/suite/writer_immediate.rs
@@ -0,0 +1,130 @@
+//! The writer connection's transactions must start IMMEDIATE.
+//!
+//! A deferred transaction that has already read (taken a WAL read
+//! snapshot) cannot wait through the busy handler: when another process
+//! holds the write lock, the read-to-write upgrade fails at once with
+//! `SQLITE_BUSY` ("database is locked"). In production an external
+//! `PRAGMA wal_checkpoint(TRUNCATE)` ran while the server was up, and
+//! `/hook/batch` items — whose admission reads the session row before
+//! its first write — failed immediately despite `busy_timeout = 5000`.
+//!
+//! `Store::open` sets the writer connection's transaction behavior to
+//! `IMMEDIATE`, so `BEGIN` takes the write lock up front and the busy
+//! handler waits out the external lock. This test holds the write lock
+//! with an independent connection (the external process's shape),
+//! releases it while the writer operation is in flight, and proves the
+//! operation survived by waiting ~300 ms instead of failing.
+
+use std::path::PathBuf;
+use std::thread;
+use std::time::{Duration, Instant};
+
+use ai_memory_core::{
+ AgentKind, NewObservation, NewSession, ObservationKind, OwnerFilter, Sanitized, Sanitizer,
+ SessionId,
+};
+use ai_memory_store::{HookSessionAdmission, Store};
+use rusqlite::Connection;
+
+#[tokio::test]
+async fn writer_hook_admission_survives_external_write_lock_held_during_read_then_write() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let ws = store
+ .writer
+ .get_or_create_workspace("lockwait")
+ .await
+ .unwrap();
+ let proj = store
+ .writer
+ .get_or_create_project(ws, "lockwait".to_string(), None)
+ .await
+ .unwrap();
+
+ // The external process's lock: an active write transaction, the
+ // shape of an external checkpoint or sqlite3 shell holding the write
+ // lock while the server runs.
+ let db_path = tmp.path().join("db").join("memory.sqlite");
+ let external = Connection::open(&db_path).unwrap();
+ external
+ .execute_batch(
+ "BEGIN IMMEDIATE; CREATE TABLE external_lock_probe (x INTEGER); \
+ INSERT INTO external_lock_probe VALUES (1);",
+ )
+ .unwrap();
+
+ // Hold the lock for ~300 ms — well inside the writer connection's
+ // 5000 ms busy timeout — then release it while the writer
+ // operation is in flight.
+ let release = thread::spawn(move || {
+ thread::sleep(Duration::from_millis(300));
+ external
+ .execute_batch("COMMIT; DROP TABLE external_lock_probe;")
+ .unwrap();
+ });
+
+ let session_id = SessionId::new();
+ let session = NewSession {
+ occurred_at: None,
+ id: session_id,
+ workspace_id: ws,
+ project_id: proj,
+ agent_kind: AgentKind::Codex,
+ cwd: Some(PathBuf::from("/repo")),
+ actor_user: None,
+ };
+ let raw_obs = NewObservation {
+ occurred_at: None,
+ session_id,
+ workspace_id: ws,
+ project_id: proj,
+ kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
+ title: "checkpoint lock wait".into(),
+ body: "the writer must wait out an external checkpoint".into(),
+ importance: 5,
+ };
+
+ let started = Instant::now();
+ // The hook-batch admission reads the session row (ops.rs,
+ // `SELECT ... FROM sessions WHERE id = ?1`) before its first write,
+ // so a deferred transaction here has a read snapshot to invalidate
+ // at the upgrade.
+ let admission = store
+ .writer
+ .admit_hook_session_event(
+ session,
+ Sanitized::new(raw_obs, &Sanitizer::builtin()),
+ OwnerFilter::Any,
+ None,
+ None,
+ )
+ .await
+ .expect(
+ "a deferred transaction that already read fails with bare SQLITE_BUSY at the \
+ upgrade; an immediate transaction waits through the busy handler",
+ );
+ let elapsed = started.elapsed();
+ release.join().unwrap();
+
+ assert!(
+ matches!(admission, HookSessionAdmission::Observation { .. }),
+ "the hook event is admitted once the external lock clears: {admission:?}"
+ );
+ // It waited out the held lock (~300 ms) instead of racing it: a
+ // write that did not wait would have returned near-instantly.
+ assert!(
+ elapsed >= Duration::from_millis(200),
+ "returned after {elapsed:?} without waiting out the external lock"
+ );
+ // And the data is on disk once the external lock cleared.
+ assert!(
+ store
+ .reader
+ .session_has_substantive_observation(ws, proj, session_id)
+ .await
+ .unwrap(),
+ "the observation is committed once the external lock clears"
+ );
+}