diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-12 15:04:44 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-12 15:04:44 +0000 |
| commit | 285e0fd4a43a10f87e2689dbb76be9e102fb2fa1 (patch) | |
| tree | 431ad720d13d5a8a1d2b95640a0c8ef96b476c16 | |
| parent | 9f11abe6e1d0e961124c6c8073ec48f3927f5c61 (diff) | |
| download | ai-memory-285e0fd4a43a10f87e2689dbb76be9e102fb2fa1.tar.gz | |
Add a README and a BSD 3-Clause licence
The project had no README: the only prose was doc/SKILL.md, which is the working protocol for an assistant already using the tool, not an introduction to it. README.md now says what the store is for (a session's context is finite and the conversation is gone when it ends; the diff says what, not why), what it stores (three derived tables, one authored), how to build it, and the vocabulary it needs: why / search / record / attach / sync / log / status, with the topic index and its prefixes, the rules the tool relies on (append-only reasoning, --supersedes, --basis) and the two limits worth knowing up front -- the store is per repository and local, so a fact spanning repos needs recording in each and anything that must outlive the machine belongs in commits and docs too. The examples are real output from this deployment's own stores, not invented: the why entry shows the [fn file.function, context] annotation and the reasoning under it, log shows the per-commit reasoning counts, status the row counts. The record examples were run against a scratch store before being written down. LICENSE is BSD 3-Clause (Copyright (c) 2026 Pjotr Prins), which also settles the TODO in guix.scm: the package now declares license:bsd-3 instead of the placeholder expat. The package installs README.md and doc/SKILL.md beside the binary under share/doc/ai-memory/; LICENSE travels in share/doc/ai-memory-<version>/ from the standard install-license-files phase, so it is not installed twice.
| -rw-r--r-- | LICENSE | 29 | ||||
| -rw-r--r-- | README.md | 172 | ||||
| -rw-r--r-- | guix.scm | 10 |
3 files changed, 209 insertions, 2 deletions
diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..5a0e34a --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +BSD 3-Clause License + +Copyright (c) 2026, Pjotr Prins <wrk@bosa.lan> +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ecc085f --- /dev/null +++ b/README.md @@ -0,0 +1,172 @@ +# ai-memory + +Memory for an AI assistant working in a git repository: it links **what +changed** (derived from git) to **why it changed** (written by the assistant +while working), so the next session can recover it. + +A session's context window is finite, and the conversation that produced a piece +of work is gone when it ends. The diff, the tests and the commit messages say +*what* happened; they rarely say what was tried and rejected, what a number was +measured against, or which four things had to be fixed before something ran at +all. `ai-memory` keeps that, per repository, in one SQLite file, and answers +three questions quickly: + +```sh +ai-memory -C REPO why SYMBOL # which commits touched this, and what was the reasoning? +ai-memory -C REPO search TEXT # full-text over the reasoning: ~15 ms +ai-memory -C REPO log # recent commits, and how much reasoning each carries +``` + +## What it stores + +| table | source | contents | +|---|---|---| +| `commits` | derived | hash, author timestamp, subject, body | +| `symbols` + `touches` | derived | every declaration a commit added, modified, removed, or merely *enclosed* (hunk context) | +| `reasoning` | **authored** | append-only thoughts, conclusions and questions, each with its basis and an optional `supersedes` link | + +`sync` owns the derived rows; only the `reasoning` table is written by hand +(through the tool). That split is the point: the git half is always true of the +tree, and the authored half can never be rewritten — a change of mind is a new +entry that supersedes the old one, and both stay on the record. + +## Install + +```sh +guix build -f guix.scm # → /gnu/store/…-ai-memory/bin/ai-memory +``` + +`guix.scm` builds the Odin compiler and the SQLite bindings it needs, so the +first build is not quick (Guix does not substitute Odin). For hacking on it, +the header of `guix.scm` lists the `odin build` line the package uses, and +`guix shell -D -f guix.scm -- odin version` gets you a compiler shell. + +The optional topic index shells out to a small Guile program +(`scripts/index.scm`) because `libxapian` is C++-only and +[guile-xapian](https://git.systemreboot.net/guile-xapian/) already ships the C++ +shim a foreign call would need. That pulls in `guile-3.0`, +`guile-xapian` and `guile-sqlite3`; core commands need none of them. + +## Quick start + +```sh +cd path/to/repo +ai-memory init # create/upgrade ai-memory.sqlite +ai-memory import # whole history (first time only) +ai-memory sync # after each commit: recent commits only +``` + +Record as you work. Bodies are for a reader who has none of the conversation, +and every entry says how it was established: + +```sh +ai-memory record --session fix-parser --step 1 --kind thought \ + --basis 'read at src/parse.rs:120-180' \ + --body "Hunk headers name the enclosing fn; a new fn needs the declarative scan." + +ai-memory record --session fix-parser --step 2 --kind conclusion \ + --basis 'measured on the bxd panel' \ + --body "Keep both signals. Add ctags only if add/remove proves noisy." + +# before the commit exists, there is nothing to attach to +ai-memory record --session fix-parser --step 3 --kind question --commit none \ + --body "Should a symbol that moved keep its old name in the index?" +``` + +Then commit, and attach the entries to it: + +```sh +git commit -am "parse: keep both signals; defer ctags" +ai-memory sync +ai-memory attach HEAD --session fix-parser +``` + +Asking afterwards — the output is one line per commit that touched the symbol, +followed by its reasoning: + +``` +$ ai-memory why variance_components_note +3a42b5f 2026-11-11T17:04:58Z gemma: the pve note carries every chromosome [fn gemma.variance_components_note, context] + #5 conclusion: Only the range or every chromosome? The first version chose the range plus the two + extremes to keep the note short -- wrong, and caught in review: under --loco each pve belongs to + a different kinship matrix ... +cd3e65b 2026-11-11T15:54:15Z gemma: report GEMMA's own pve for the null model [fn gemma.variance_components_note, add] + #1 thought: Whether GEMMA's -pve works with -lmm 9 under --loco was unknown ... +``` + +`[fn file.function, add]` means the declaration was added by that commit; +`context` means a hunk landed inside it. `log` shows which commits still carry +nothing, i.e. which are worth annotating: + +``` +$ ai-memory log --limit 3 +7a78dce 2026-11-12T14:58:13Z docs: say that project memory is how a session recovers (1) +d507d32 2026-11-12T14:45:16Z gemma/ravanan: resolve the same inputs as the direct runner (3) +60420b6 2026-11-11T21:26:07Z docs: which reference genome the coordinates are on (3) + +$ ai-memory status +commits: 286 +symbols: 1901 +touches: 3362 +reasoning: 31 +``` + +## The topic index (optional) + +Derived, disposable, and over the same store: one Xapian document per reasoning +entry and per commit, so a reader can enter by **concept** instead of by symbol. + +```sh +ai-memory --index DIR update-index [--rebuild] +ai-memory --index DIR search 'topic:pve repo:genenetwork4' +ai-memory --index DIR search --limit 5 'type:commit ravanan' +``` + +Prefixes: `topic:`, `repo:`, `type:` (`reasoning`|`commit`), `session:`, +`commit:` (7-character hash), `date:` (`yyyymmdd`). Free text is stemmed; the +default operator is AND, `--or` widens it. Topic terms come from the session id +split on hyphens — a session named `gemma-pve` answers `topic:gemma` and +`topic:pve`, and a commit inherits the topics of the reasoning attached to it. +Naming a session after a concept is how that concept becomes an entry point. + +The index directory defaults to `<store>.d/index`; `--index` or +`$AI_MEMORY_INDEX` overrides it, `$AI_MEMORY_INDEX_SCRIPT` the script. +Deleting it and running `update-index --rebuild` is always safe: SQLite is the +source of truth, the index is a projection of it. + +## Where the store lives + +`<repo>/ai-memory.sqlite`, or `--db PATH`, or `$AI_MEMORY_DB`. Neither the store +nor the index belongs in git (they are in `.gitignore`). + +Two consequences worth stating plainly: + +- the store is **per repository**, so a fact that spans repositories has to be + recorded in each, or found through one index with a `repo:` filter; +- the store is **local**, so it survives a cleared session but not a lost + machine. Anything that must outlive the box belongs in a commit message and + in the project's docs as well — which is why every entry here is paired with + a commit that says the same thing in its own words. + +## Rules the tool relies on + +- **Never write to `commits`, `symbols` or `touches`.** They are derived; + `sync` overwrites them. +- **`reasoning` is append-only.** A change of mind is a new entry with + `--supersedes ID`: the old row stays, and `why`/`search` answer with the + correction. `--all` shows the whole chain. +- **One session per task**, monotonically increasing `--step`; `(session, step, + kind)` is unique, so re-running a step is a no-op. +- **Say how it was established** (`--basis`): a measurement, a file and line + range, a commit message, or plainly `inferred`. Inference and observation look + identical in prose, which is exactly what makes a wrong entry unrecognisable + later. + +Two files document the practice in more depth: [`doc/SKILL.md`](doc/SKILL.md) +(the working protocol, the index, and *session continuity* — how a cleared +context recovers), and the code itself, which is four `.odin` files plus +`schema.sql`. + +## Licence + +BSD 3-Clause. See [LICENSE](LICENSE). diff --git a/guix.scm b/guix.scm index 72ab494..3f5691c 100644 --- a/guix.scm +++ b/guix.scm @@ -293,6 +293,12 @@ to link the system SQLite3 instead of a bundled copy.") ;; ../share/ai-memory/index.scm beside it. (install-file "scripts/index.scm" (string-append #$output "/share/ai-memory")) + ;; LICENSE lands in share/doc/ai-memory-<version>/ from the + ;; standard install-license-files phase. + (install-file "README.md" + (string-append #$output "/share/doc/ai-memory")) + (install-file "doc/SKILL.md" + (string-append #$output "/share/doc/ai-memory")) (wrap-program (string-append #$output "/bin/ai-memory") `("GUILE" = (,(string-append #$(this-package-input "guile") "/bin/guile"))) `("GUILE_LOAD_PATH" = (,(string-append #$(this-package-input "guile-xapian") @@ -304,7 +310,7 @@ to link the system SQLite3 instead of a bundled copy.") (description "ai-memory is a store for facts that an AI assistant should remember across sessions. It keeps them in a SQLite database.") - ;; TODO: pick the license once the project settles on one. - (license license:expat))) + ;; BSD 3-Clause, see LICENSE. + (license license:bsd-3))) ai-memory |
