about summary refs log tree commit diff
diff options
context:
space:
mode:
authorPjotr Prins <pjotr.public01@thebird.nl>2026-11-11 22:07:21 +0000
committerPjotr Prins <pjotr.public01@thebird.nl>2026-11-11 22:07:21 +0000
commit8bece744619316593ddfbc81fd84c096794a6a79 (patch)
tree63b6889de78d2cba69819bbcdd18f7aa8ff4fa47
parentaa6fe5369c7733e8bc881623ab6734cfef9cb66c (diff)
downloadai-memory-8bece744619316593ddfbc81fd84c096794a6a79.tar.gz
ignore any SQLite store; document repairing a rewritten commit hash
.gitignore now ignores *.sqlite and *.sqlite-*, so a store written by --db or
$AI_MEMORY_DB is never committed under a different name.

doc/SKILL.md gains a "Rewriting history" section: amend/rebase/squash leave
touches and reasoning attached to hashes that no longer exist, sync only ever
adds, and the foreign-key cascade that removes the stale commit's touches is
off unless pragma foreign_keys=on is set in the sqlite3 CLI.
-rw-r--r--.gitignore10
-rw-r--r--doc/SKILL.md26
2 files changed, 32 insertions, 4 deletions
diff --git a/.gitignore b/.gitignore
index 0364839..0c2a929 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,7 @@
-# the store is local working memory, not source
-/ai-memory.sqlite
-/ai-memory.sqlite-*
-# local build output of `odin build . -out:bin/ai-memory'
+# The store is local working memory, not source: any SQLite file in this repo
+# is data, whatever --db or $AI_MEMORY_DB named it.  Never commit it.
+*.sqlite
+*.sqlite-*
+
+# Local build output of `odin build . -out:bin/ai-memory'.
 /bin/
diff --git a/doc/SKILL.md b/doc/SKILL.md
index 717b84b..fb17189 100644
--- a/doc/SKILL.md
+++ b/doc/SKILL.md
@@ -101,6 +101,29 @@ committing even if `sync` has not run yet.
   in `.gitignore`; commit only source.  Importing history is read-only — `-C`
   never touches the working tree.
 
+## Rewriting history
+
+`git commit --amend`, `rebase` and `squash` change commit hashes.  Every
+`touches` and `reasoning` row attached to the old hash is then stale, and `sync`
+will **not** clean it up — it only adds.  The repair, in this order:
+
+1. detach the reasoning for the old hash:
+   `update reasoning set commit_hash = null where commit_hash = '<old>'`
+2. `ai-memory -C REPO sync` — imports the new hash
+3. `ai-memory -C REPO attach <new|HEAD> --session S` — re-links the entries
+4. delete the old commit row:
+   `pragma foreign_keys=on; delete from commits where hash = '<old>'`
+
+Step 4 needs the pragma: the `sqlite3` CLI leaves foreign keys **off**, so the
+delete runs without cascading and the old commit's touches stay behind as
+orphans.  Nothing complains — `status` just reports double the touches, and
+`why` points at a hash that is no longer in `git log`.  Check afterwards with
+`pragma foreign_key_check` and by counting rows whose `commit_hash` has no
+matching `commits` row.
+
+This is the one place where hand-written SQL is correct: the tool repairs
+nothing.  Amending *before* recording is cheaper than repairing afterwards.
+
 ## Interpretation
 
 - `[fn gemma.compute_gemma, context]` means a hunk landed *inside* that function,
@@ -119,6 +142,9 @@ committing even if `sync` has not run yet.
 - `no commits to import` — the repo has no history yet, or `--repo` points elsewhere.
 - `why` finds nothing — run `sync` first; or the symbol lives in a file type we do
   not parse for declarations.
+- Touch counts looking double, or a commit in the output of `log` that is not in
+  `git log` — a hash was rewritten (amend/rebase).  See *Rewriting history*; the
+  stale rows do not repair themselves.
 - `search` finds nothing after manual DB edits — FTS is trigger-maintained; rebuild
   with `insert into reasoning_fts(reasoning_fts) values('rebuild')`.
 - Direct inspection is fine (read-only):