about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-12 14:58:13 +0000
committerPjotr <wrk@bosa.lan>2026-11-12 14:58:13 +0000
commit7a78dce4bf6db058f1ac12a4176c2702debff798 (patch)
treee54924b1881fd0850ea51a4b43f75cdc6eaeb07c /docs
parentd507d3220910f528d95932f7772f80a902ec6fe9 (diff)
downloadgenenetwork4-7a78dce4bf6db058f1ac12a4176c2702debff798.tar.gz
docs: say that project memory is how a session recovers, and where it lives
The ai-memory store already existed; what was missing was any mention that a
reader should use it before starting work, and what they would find. Two
concrete things a cold reader needs and cannot reconstruct from a diff: an
operational RUNBOOK entry (the Slurm container from gn-machines, its fixed JWT,
the environment /compute/gemma/ravanan needs, the four prerequisites that bit
the first time, and the fastest test: one chromosome, 14 s), and the "why is
this like this" entries behind endpoints that exist because something else was
wrong (-pve reporting, the next-link graph, the reference-genome linkage).

docs/www/SKILL.md gains section 7a with the three query forms, the topic names
that exist (ravanan-slurm, reference-genomes, gemma-pve) and both measured
costs; README gains the same note under Development, since that is where a
maintainer looks first.

States the limit honestly: the store is local, gitignored and per repository --
it survives a cleared session, not a lost machine, which is why every
conclusion is also in a commit message and in these docs.
Diffstat (limited to 'docs')
-rw-r--r--docs/www/SKILL.md33
1 files changed, 33 insertions, 0 deletions
diff --git a/docs/www/SKILL.md b/docs/www/SKILL.md
index 518e233..4bb81e4 100644
--- a/docs/www/SKILL.md
+++ b/docs/www/SKILL.md
@@ -582,6 +582,39 @@ you saw at the start of the session** and compare against it later.
    `/gn4/openapi.json`, which always matches the running server, and tell the
    user the skill file itself could not be refreshed.
 
+## 7a. Project memory: the answers this repo has already worked out
+
+This repository carries an `ai-memory` store (`ai-memory.sqlite`) linking each
+commit to the reasoning behind it, plus an optional Xapian topic index over
+both. A previous session's context window is gone; this is what survives it,
+and it is cheaper than re-deriving anything:
+
+```sh
+ai-memory -C genenetwork4 search 'pve'          # SQLite FTS over the reasoning: ~15 ms
+ai-memory -C genenetwork4 why gemma.compute_gemma   # commits touching a symbol, with its reasoning
+ai-memory -C genenetwork4 --index DIR search 'topic:pve repo:genenetwork4'   # topic index: ~100 ms
+```
+
+`topic:` terms come from the session id, so `topic:ravanan-slurm`,
+`topic:reference-genomes`, `topic:gemma-pve` are the entry points that exist.
+
+Two things to look for before starting work that touches an engine, a cache or
+a cluster:
+
+- **a RUNBOOK entry** — the operational ones carry the actual commands, ports
+  and fingerprints, e.g. bringing up the Slurm container from `gn-machines` and
+  testing `/compute/gemma/ravanan` against it, with the four prerequisites that
+  were needed the first time (a ravanan build with the `--slurm-api-endpoint`
+  fix, `ccwl` on `PATH`, the server's `HOME` writable inside the container,
+  `GUIX_PACKAGE_PATH` for the manifest);
+- **a "why is this like this" entry** — several endpoints here exist because
+  something else was wrong (`-pve` reporting, the `next`-link graph, the
+  reference-genome linkage). Reading it is faster than deciding they are odd.
+
+The store is per repository and local (gitignored): it survives a cleared
+session, not a lost machine, which is why the durable version of every
+conclusion is also in a commit message and in these docs.
+
 ## 8. Reference docs
 
 The docs live in the public repo and are the authoritative version: