dsh-project-memory

LIMITATIONS

Known limitations

- **Recall is lexical.** Exact token hits plus a character n-gram fallback — there are no embeddings. A rephrased problem may not match; `memory_search` is the escape hatch. - **The n-gram fallback is loose for short records.** Jaccard over few n-grams reaches the 0.12 floor easily: two short, barely related texts sharing one bigram can score ≈ 0.2, clear the floor, and (if `minScore` is met) be recalled. Lower `maxRecallRecords` or raise `minScore` when this matters. - **No persisted inverted index** — the candidate set is scored per recall from the in-memory domain table; the per-project id index is a rebuildable convenience repaired from the records table on open. Fine at hundreds of records; not measured at tens of thousands. - **Precision is preferred over recall.** `minScore` (default 3) drops weak candidates silently; a marginal record can miss injection at score ≈ 4. - **The audit trail is in-memory** — bounded, lost on restart. - **A second process's in-memory view stays stale until it reopens.** The lease makes concurrent *writes* safe; reads still come from the table the domain seeded at open, so a record another process added mid-session is listed in the index but resolves to nothing here until this process restarts. - **Lease release is not atomic, and that is a real risk rather than a proven defect.** `releaseLease` reads the lock, compares its owner token, and only then removes it. A takeover landing between the read and the removal would make it delete a *successor's* lock and admit a third writer. No probe has reproduced that interleaving and no test covers it, so it is recorded here as a known risk; closing it needs a primitive that owns an open handle (or `flock`) rather than a path. The same is true of the mutual exclusion itself: it holds only up to `leaseWaitMs` — see *Concurrent writers*. - **Project identity is the working directory**, so one repository opened from two different directories (its root in one session, a subdirectory in another) is treated as two projects. Records do not cross that line. Anchor sessions at the repository root, or the memory will look empty from the other directory. - **One working directory is one pool.** Several subsystems developed under the same root — say `job_agent_mvp/`, `_site/v3/`, and a plugin in a sibling directory you also open here — share one record set and one recall ranking; recall does not separate them by path or subsystem. A record's `related_files` carries the path, but nothing requires an overlap before a record is injected. This is a known boundary, not a bug: splitting the pool would change how recall ranks, and that needs real-sample comparison before it is designed. - **Recording depends on the model following the contract.** The contract text is deliberately prescriptive: a purely permissive wording produced zero writes in testing.