documentation update

docs/services/memory-service.md

@@ -78,6 +78,11 @@ does **not** reconcile columns on old tables — that's what migrations are for)
 ```js
 const migrations = [
   (_db) => {},   // v0 → v1: consolidated baseline (historical ALTERs folded into schema.js)
+  (db) => {      // v1 → v2: access tracking for consolidation lifecycle
+    db.exec(`ALTER TABLE episodes ADD COLUMN last_accessed_at INTEGER`);
+    db.exec(`ALTER TABLE episodes ADD COLUMN access_count INTEGER NOT NULL DEFAULT 0`);
+    db.exec(`UPDATE episodes SET last_accessed_at = created_at`);  // backfill
+  },
 ];
 const LATEST_VERSION = migrations.length;  // derived, never hand-maintained
 ```
@@ -121,6 +126,12 @@ previously ran on every startup.
 - `foreign_keys = ON` — enforces referential integrity and cascade deletes
 - PRAGMAs set via `db.pragma()`, not `db.exec()`
 
+> **Copying a live WAL database:** `cp` on the `.db` file alone silently loses
+> everything in the un-checkpointed `-wal` file (recent writes, even the
+> migration version stamp). Always use
+> `sqlite3 nexusai.db "VACUUM INTO './copy.db'"` (or `.backup`) — safe while
+> the service is running, produces a complete single-file snapshot.
+
 ### Dynamic Updates
 
 Both `updateSession` and `updateProject` build their `SET` clause dynamically
@@ -204,6 +215,28 @@ service is responsible only for CRUD — generation logic lives in orchestration
 > For full details on trigger conditions, prompt format, cumulative updates,
 > and ChatML token stripping, see `summarization.md`.
 
+## Access Tracking & Consolidation (dry-run)
+
+Every episode selected into a chat context window (budget-selected, not the
+guaranteed-recency floor) gets an access bump via `POST /episodes/touch` —
+`access_count` incremented, `last_accessed_at` set to `Date.now()` (ms).
+Called fire-and-forget from orchestration; a failure loses one increment,
+nothing more.
+
+`GET /sessions/:id/consolidation-candidates` scores episodes by
+`access_count / (1 + days since last access)` — never-accessed episodes fall
+back to `created_at` for the recency term and score exactly 0 (most eligible).
+Two floors apply: episodes younger than `CONSOLIDATION.MIN_AGE_DAYS` are
+excluded in SQL; sessions under `CONSOLIDATION.MIN_SESSION_EPISODES` return
+`eligible: false` before scoring runs. The endpoint is observe-only — the
+destructive pass (merge → summarize → Qdrant cleanup → orphan sweep) is not
+yet built.
+
+> **Unit note:** `created_at` is unix **seconds** (`unixepoch()`);
+> `last_accessed_at` is unix **milliseconds** (`Date.now()`). The scoring
+> query normalizes with `created_at * 1000`. Keep this in mind for any new
+> queries touching both columns.
+
 ## Delete Behaviour (SQLite + Qdrant consistency)
 
 SQLite cascades handle relational cleanup, but Qdrant is a separate store and