AbstractMemory 0.3.2__tar.gz → 0.4.0__tar.gz

{abstractmemory-0.3.2 → abstractmemory-0.4.0}/CHANGELOG.md

@@ -5,9 +5,154 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) (pre-1.0).
 
-## Unreleased
+## [0.4.0] - 2026-10-27
+
+The memory graph ([ADR 0003](docs/adr/0003-one-graph-ledger-provenance-and-revisions.md), backlogs 0056-0058):
+`abstractmemory.graph.MemoryGraph` is the only manipulation surface of a mind; every change is a revision, every
+memory points back to the ledger, and every database is a connector behind the graph (SQLite the default). The home
+store holds a notebook-sized corpus. The API is additive: every 0.3.x call keeps working (`close_assertion` stays;
+`ClosureRecord` gains only the `merged` kind). Operator decisions adopted (2026-10-27): visibility is strict
+ownership (lineage never crosses owners; ADR 0003 decision 2); stores are connectors behind `MemoryGraph`, SQLite the
+default (decision 3); the vector re-encoding below is a documented one-way migration with a `vector_encoding` marker.
+
+### Upgrade notes: ONE-WAY migration
+
+- Opening a SQLite home with 0.4.0 rewrites its JSON-text vectors as float32 BLOBs. A 0.3.x reader decodes JSON
+  vectors only: on a home a 0.4.0 process has written it silently finds no vectors (zero semantic hits, no error).
+  Every process sharing a home or a plane must move to 0.4.0 together; an entity home copied to a 0.3.x install
+  loses semantic recall. A 0.4.0 home declares it: `<table>_meta` key `vector_encoding` = `float32-blob`
+  (`abstractmemory.vector_matrix.VECTOR_ENCODING_KEY`), written by the first write or by the upgrade, never by a
+  plain open.
+- Graph homes add four tables (`memg_revisions`, `memg_provenance`, `memg_derivations`, `memg_history`) on first
+  use; nothing else in an existing file changes shape.
 
-*No unreleased changes.*
+### Added
+
+- **Connectors** (ADR 0003 decision 3, operator decision 2026-10-27): `MemoryGraph` is the only manipulation
+  surface of a mind and every store is a connector behind it: `abstractmemory.graph.backend` (`GraphBackend`,
+  `GraphTx` Protocols with their invariants; `register_backend`, `backend_for`, `registered_backends`). SQLite (the
+  default for planes and entity homes) and in-memory are declared implementations; a new LanceDB connector
+  (`abstractmemory.graph.lancedb_backend`, over `LanceDBTripleStore`: explicit Arrow schemas, a staged transaction,
+  a log-first commit, `repair()` re-derives a half-projected revision from the log). One conformance suite,
+  `tests/test_graph_conformance.py`, runs every connector; the LanceDB connector cannot promise serialized writers
+  across processes nor invisibility of a half-projected revision before `repair()` (strict xfails).
+- **`abstractmemory.graph`**, the one write path of a mind:
+  - `SourceRef` (`run`, `step` with the ledger row address `(run_id, seq)`, `seq` 1-based, `artifact`, `message`, `event`,
+    `diary_entry`; optional `runtime_id`; one canonical `key()`), validated per kind (`InvalidSourceRef`); a
+    `run` / `step` ref naming a synthetic run id (`SYNTHETIC_RUN_ID_PREFIXES`: `chat-`, `diary:`,
+    `session_memory_`, `global_memory`) is refused.
+  - `Provenance(sources, derived_from, actor, reader, reason, extra)`, strict about its shape;
+    `Provenance.from_legacy(...)` lifts the old flat keys (`run_id`, `span_id`, `payload_ref`, `entry_id`, ...)
+    in one place, never fabricates a reference (a synthetic run id stays in `extra`), and reads the mixed shape
+    the runtime stamps (flat keys plus `sources`: flat keys into `extra`).
+  - `Revision` (`revision_id`, `scope`, `owner_id`, `cause`, `occurred_at`, `recorded_at`, `ops`, `provenance`,
+    `summary`) with the ops `assert`, `close` (`retract` / `supersede` / `reinterpreted` / `merged`, replacement
+    ids, ripple source and hops) and `narrow`. Every time a revision carries is parsed and normalized to one
+    UTC text form; a non-timestamp is refused. A close ends the row at the earlier of its current end and the
+    close (so `TripleQuery(active_at=)` and ranked recall agree after every close); a close or narrow before the
+    claim's `valid_from` is refused.
+  - `MemoryGraph(store, journal).apply_revision(rev)`: refuses a memory that is neither sourced nor derived from a
+    grounded memory (`ProvenanceRequired`; chains that never reach a source and cycles included); applies all ops
+    in ONE SQLite transaction (triples and their keyword rows, window changes, the journal closure when the
+    journal shares the file, the revision, provenance, derivation and history rows), or not at all; idempotent on
+    the revision id; deterministic ids so the logged revision replays identically. A store row written outside
+    the graph is adopted only by an `import` / `migration` revision that carries it as stored (logged with its
+    previous provenance, so a replay reproduces it); a different claim under an id the graph holds is refused;
+    a close/narrow-only revision must name a cause other than the memories it changes; a `derived_from` across
+    owners is refused (other owners' knowledge enters as a source). Re-observation, not duplication: an open
+    assert of a claim the graph holds open records its sources on the held memory (`re_observed`, history
+    `re-observed`) instead of a second row. Record time is the store's: a fresh apply stamps `recorded_at` with
+    its clock (`apply_revision(rev, replay=True)`, used by `replay_into`, keeps the logged value). A revision
+    already in the log returns its logged outcome. Every memory is also indexed by the sources of the revision
+    that wrote it (`via`). `SourceRef.digest`: an optional sha256 of the verbatim, beside the address.
+  - Reads, all bounded index reads: `history(memory_id)` (asserted / closed / narrowed, by which revision, with
+    its cause), `sources_of(memory_id, transitive=True)`, `derived_from_source(ref)` (a `run` ref matches
+    everything stamped with that run), the lossless change feed `revisions(after=cursor)` (a cursor beyond the
+    log's head is refused), `replay_into(target)` (an empty home replays to the same file, adoptions included),
+    `names_ref(ref, owner_ids)` (the owner gate in one index probe), and `repair()` for closures a crash left
+    unwritten when the journal lives in another file (never needed for same-file plane and entity homes).
+  - Four tables in the home file: `memg_revisions`, `memg_provenance`, `memg_derivations`, `memg_history`.
+- **`narrow_assertion(assertion_id, valid_until)`** on `SQLiteTripleStore` and `InMemoryTripleStore`: moves an
+  already-closed validity window earlier and never widens it (`ValueError` for an open window or a value that is
+  not a timestamp; `False` for an unknown id or a date at or after the current end, compared as instants). `LanceDBTripleStore.narrow_assertion` raises
+  `NotImplementedError` (on LanceDB a window changes through the graph's LanceDB connector). AbstractNote no longer
+  needs to write the store's private table.
+- **Closure kind `merged`** (`abstractmemory.journal.CLOSURE_KINDS`): the memory was merged into another, named in
+  `replacement_ids`. `close_assertions` and `close_record` accept it.
+- Docs: `api.md` (the graph section and its tables), `memory-system.md` ("Time axes", "Provenance").
+- Measured at 50,000 assertions (`tests/bench/bench_graph.py`): `history` 0.02 ms, `sources_of` 0.04 ms,
+  `derived_from_source` by step 0.05 ms and by run 0.8 ms, a change-feed page of 100 revisions 4 ms; the 0.3
+  alternative (scanning provenance JSON) took 18 ms on vectorless rows and 38 ms with 384-d vectors in the rows.
+
+### Performance (0058)
+
+Backlog 0058 (ADR 0003 decisions 3 and 12): the SQLite home store holds a
+notebook-sized corpus. Measured with `tests/bench/bench_store.py`, `main`
+versus this release on the same machine, back to back: subject + owner query
+at 50k rows 14.8 ms -> 0.33 ms; scope "latest 100" 377 ms -> 0.9 ms; scope
+full scan 2.6 s -> 0.5 s; vector query at 50k 5.3 s -> 1.4 ms (first query of
+a handle 0.44 s, it builds the matrix); file 449 MB -> 122 MB; MemorySystem
+`reconstruct` at 20k records 2.7 s -> 0.2 s; `maintenance_due` at 20k 1.9 s ->
+0.07 ms when nothing is new, 0.1 s after new records. Full table: backlog
+0058's Report.
+
+- **Owner-filtered reads use the indexes.** The owner filter is now
+  `owner_id = ?` instead of `COALESCE(owner_id, '') = ?` (same rows: the
+  filter only applies to a non-empty owner, which a NULL or empty stored owner
+  never equals). A new index `idx_<table>_scope_owner_observed (scope,
+  owner_id, observed_at, assertion_id)` serves "latest N in a (scope, owner)",
+  as-of windows and per-pair scans in query order without sorting the
+  partition; reads anchored on ids, a subject or an object use their own index
+  and check scope/owner per row. Existing homes gain the index when the store
+  is opened; no row is rewritten. `SQLiteTripleStore.query_plan(q)` returns
+  SQLite's `EXPLAIN QUERY PLAN` lines for a query (tests pin the plans).
+- **Structured reads no longer fetch the vector column.** `query` (without
+  `query_text`/`query_vector`) and `query_keywords` select the assertion
+  columns only, instead of `SELECT *` dragging the stored embedding (several KB
+  per row) and the canonical text through every scan. They no longer read the
+  embedding pin either (it guards semantic queries only). Semantic queries and
+  `stored_vector` still read the vector; `TripleAssertion` is unchanged.
+- **Vectors are float32 BLOBs.** `SQLiteTripleStore` stores vectors as float32
+  little-endian BLOBs (4 bytes per dimension instead of ~20 bytes of JSON
+  text). Homes holding JSON vectors are upgraded in place when the store opens:
+  rows above the `vector_blob_high_water` cursor are rewritten in bounded
+  transactions (idempotent; an interrupted upgrade resumes; ~5 s once for 50k
+  rows of 384-d vectors). Stored precision is float32: a score differs from
+  the float64 value an embedder returned by about 1e-7. A value float32 cannot
+  hold raises `ValueError` at write (zero rows written) instead of being
+  stored as infinity; `stored_vector` returns the float32 values. One-way: see
+  "Upgrade notes" above.
+- **Opening a home is a read.** `SQLiteTripleStore` and `SQLiteJournal` take no write lock when opening an
+  up-to-date home (the keyword-index and vector backfills run only when there is work; every insert path keeps
+  their cursors at the head; the journal checks its schema in a deferred transaction), so a reader never waits
+  behind a writer (before: up to `busy_timeout`, then "database is locked").
+- **Matrix cache footprint.** A (re)build reserves exactly the table's vector rows (one allocation); appends
+  grow by at most 10 % (`store_tuning.VECTOR_MATRIX_GROWTH`; no doubling). Per process that queries a home:
+  rows x dims x 4 B plus about 170 B per row (`store_tuning.py`). Measured at 100k x 1024: 424 MB held (552 MB
+  with doubling), build peak 460 MB (833 MB).
+- **Vector queries from an in-process matrix cache.** With numpy installed
+  (new extra `abstractmemory[fast]`; also in `all`, `all-apple`, `all-gpu`
+  and `test`), vector queries are served from a float32 matrix built at a
+  handle's first semantic query, appended with rows written since by any
+  handle or process, and rebuilt when the vectors are rewritten
+  (`replace_vectors`, the upgrade; `vector_generation` in the meta sidecar).
+  Results are the reference scan's (`vector_scoring.rank_by_cosine`): same
+  rows, same order (ties in rowid order), bit-identical scores — a float32
+  pass picks the candidates with a margin above its error bound, and they are
+  re-scored with the reference arithmetic. Without numpy, or when a stored
+  vector cannot be scored exactly (mixed dimensions, non-finite values), the
+  Python scan answers, labelled once per handle with a `#FALLBACK`
+  `RuntimeWarning`. `SQLiteTripleStore.vector_engine` reports the path.
+- **`maintenance_due` bounded by a cursor.** For the SQLite and in-memory
+  stores the answer is folded from the new store change feed
+  `assertions_after(cursor, *, scope, owner_id, limit)`: a check reads only the
+  rows written since the previous check of the same (store, journal, scopes)
+  and re-reads the journal's formation bindings only when the journal moved.
+  `last_maintenance_seq` uses the same fold. The answer is the full scan's
+  (other stores keep the scan).
+- Tuning constants of the store (margins, batch and page sizes) live in
+  `abstractmemory.store_tuning`, each with its bound or measurement.
+- The benchmark lives in the repository: `tests/bench/bench_store.py`.
 
 ## [0.3.2] - 2026-10-20
 

{abstractmemory-0.3.2 → abstractmemory-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractMemory
-Version: 0.3.2
+Version: 0.4.0
 Summary: AbstractMemory: temporal, provenance-aware semantic memory primitives for AbstractFramework.
 Project-URL: AbstractFramework (monorepo), https://github.com/lpalbou/abstractframework
 Author: Laurent-Philippe Albou
@@ -19,18 +19,24 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Provides-Extra: all
 Requires-Dist: lancedb; extra == 'all'
+Requires-Dist: numpy>=1.24; extra == 'all'
 Provides-Extra: all-apple
 Requires-Dist: lancedb; extra == 'all-apple'
+Requires-Dist: numpy>=1.24; extra == 'all-apple'
 Provides-Extra: all-gpu
 Requires-Dist: lancedb; extra == 'all-gpu'
+Requires-Dist: numpy>=1.24; extra == 'all-gpu'
 Provides-Extra: apple
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: fast
+Requires-Dist: numpy>=1.24; extra == 'fast'
 Provides-Extra: gpu
 Provides-Extra: lancedb
 Requires-Dist: lancedb; extra == 'lancedb'
 Provides-Extra: test
 Requires-Dist: lancedb; extra == 'test'
+Requires-Dist: numpy>=1.24; extra == 'test'
 Requires-Dist: pytest>=7.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
@@ -86,6 +92,13 @@ Optional LanceDB backend:
 python -m pip install -e ".[lancedb]"
 ```
 
+Fast vector search on the SQLite store (numpy; without it the store serves the
+same results from a labelled Python scan):
+
+```bash
+python -m pip install -e ".[fast]"
+```
+
 PyPI (packaged release):
 
 ```bash
@@ -93,7 +106,7 @@ python -m pip install AbstractMemory
 python -m pip install "AbstractMemory[lancedb]"
 ```
 
-The distribution name is `AbstractMemory` (pip is case-insensitive); the import name is `abstractmemory`. The `[apple]`/`[gpu]` extras are no-op compatibility aliases; `[all]`, `[all-apple]`, and `[all-gpu]` install the LanceDB backend.
+The distribution name is `AbstractMemory` (pip is case-insensitive); the import name is `abstractmemory`. The `[apple]`/`[gpu]` extras are no-op compatibility aliases; `[fast]` installs numpy for the SQLite store's vector matrix cache; `[all]`, `[all-apple]`, and `[all-gpu]` install the LanceDB backend and numpy.
 
 ## Quick example — layer 1 (triples)
 
@@ -141,6 +154,10 @@ result = system.reconstruct(Stimulus(cue_text="pool outage"), scopes=[("session"
 system.commit_selection(result.trace_id, [h.record_id for h in result.handles[:2]])
 ```
 
+## The memory graph: revisions and provenance
+
+`abstractmemory.graph` is the write path of a mind (0.4.0): every change to the graph is one `Revision` (a cause such as `ingest`, `reinterpret` or `maintenance`, plus `assert` / `close` / `narrow` operations applied together and atomically, once per revision id), and every memory must name where it came from in AbstractRuntime's ledger (a `SourceRef` to a run, a step `(run_id, seq)`, an artifact, a message, an event or a diary entry) or the memories it was derived from; a write with neither is refused with `ProvenanceRequired`. `MemoryGraph(store, journal)` then answers `history(memory_id)` (asserted, closed, narrowed: by which revision and why), `sources_of(memory_id)`, `derived_from_source(ref)`, a lossless change feed `revisions(after=cursor)`, and `replay_into(...)`. The database is a connector behind the graph (`abstractmemory.graph.backend`): SQLite by default, LanceDB and in-memory held to the same conformance suite. See [`docs/api.md`](docs/api.md#the-memory-graph-revisions-and-provenance) and the "Time axes" and "Provenance" sections of [`docs/memory-system.md`](docs/memory-system.md).
+
 ## Documentation
 
 - Getting started: [`docs/getting-started.md`](docs/getting-started.md)
@@ -164,7 +181,7 @@ system.commit_selection(result.trace_id, [h.record_id for h in result.handles[:2
 
 ## Design principles
 
-- **Append-only, no deletion**: updates are new assertions; belief revision is closure records (retract/supersede/reinterpreted); forgetting is decay of retrieval strength plus closures and silencing — the substrate is lossless.
+- **Append-only, no deletion**: updates are new assertions; belief revision is closure records (retract/supersede/reinterpreted/merged); forgetting is decay of retrieval strength plus closures and silencing — the substrate is lossless.
 - **Reads are pure**: reconstruction, inspection, replay, and the entity card deposit nothing. `commit_selection` is the only strengthening path.
 - **One seq axis**: the journal assigns a monotonic `seq` to every record; any past state is reproducible by anchoring reads at `as_of`.
 - **Works-or-loud**: degraded paths are labeled `#FALLBACK` in result warnings; invalid inputs raise actionable errors instead of silently meaning something else.

{abstractmemory-0.3.2 → abstractmemory-0.4.0}/README.md

@@ -50,6 +50,13 @@ Optional LanceDB backend:
 python -m pip install -e ".[lancedb]"
 ```
 
+Fast vector search on the SQLite store (numpy; without it the store serves the
+same results from a labelled Python scan):
+
+```bash
+python -m pip install -e ".[fast]"
+```
+
 PyPI (packaged release):
 
 ```bash
@@ -57,7 +64,7 @@ python -m pip install AbstractMemory
 python -m pip install "AbstractMemory[lancedb]"
 ```
 
-The distribution name is `AbstractMemory` (pip is case-insensitive); the import name is `abstractmemory`. The `[apple]`/`[gpu]` extras are no-op compatibility aliases; `[all]`, `[all-apple]`, and `[all-gpu]` install the LanceDB backend.
+The distribution name is `AbstractMemory` (pip is case-insensitive); the import name is `abstractmemory`. The `[apple]`/`[gpu]` extras are no-op compatibility aliases; `[fast]` installs numpy for the SQLite store's vector matrix cache; `[all]`, `[all-apple]`, and `[all-gpu]` install the LanceDB backend and numpy.
 
 ## Quick example — layer 1 (triples)
 
@@ -105,6 +112,10 @@ result = system.reconstruct(Stimulus(cue_text="pool outage"), scopes=[("session"
 system.commit_selection(result.trace_id, [h.record_id for h in result.handles[:2]])
 ```
 
+## The memory graph: revisions and provenance
+
+`abstractmemory.graph` is the write path of a mind (0.4.0): every change to the graph is one `Revision` (a cause such as `ingest`, `reinterpret` or `maintenance`, plus `assert` / `close` / `narrow` operations applied together and atomically, once per revision id), and every memory must name where it came from in AbstractRuntime's ledger (a `SourceRef` to a run, a step `(run_id, seq)`, an artifact, a message, an event or a diary entry) or the memories it was derived from; a write with neither is refused with `ProvenanceRequired`. `MemoryGraph(store, journal)` then answers `history(memory_id)` (asserted, closed, narrowed: by which revision and why), `sources_of(memory_id)`, `derived_from_source(ref)`, a lossless change feed `revisions(after=cursor)`, and `replay_into(...)`. The database is a connector behind the graph (`abstractmemory.graph.backend`): SQLite by default, LanceDB and in-memory held to the same conformance suite. See [`docs/api.md`](docs/api.md#the-memory-graph-revisions-and-provenance) and the "Time axes" and "Provenance" sections of [`docs/memory-system.md`](docs/memory-system.md).
+
 ## Documentation
 
 - Getting started: [`docs/getting-started.md`](docs/getting-started.md)
@@ -128,7 +139,7 @@ system.commit_selection(result.trace_id, [h.record_id for h in result.handles[:2
 
 ## Design principles
 
-- **Append-only, no deletion**: updates are new assertions; belief revision is closure records (retract/supersede/reinterpreted); forgetting is decay of retrieval strength plus closures and silencing — the substrate is lossless.
+- **Append-only, no deletion**: updates are new assertions; belief revision is closure records (retract/supersede/reinterpreted/merged); forgetting is decay of retrieval strength plus closures and silencing — the substrate is lossless.
 - **Reads are pure**: reconstruction, inspection, replay, and the entity card deposit nothing. `commit_selection` is the only strengthening path.
 - **One seq axis**: the journal assigns a monotonic `seq` to every record; any past state is reproducible by anchoring reads at `as_of`.
 - **Works-or-loud**: degraded paths are labeled `#FALLBACK` in result warnings; invalid inputs raise actionable errors instead of silently meaning something else.

{abstractmemory-0.3.2 → abstractmemory-0.4.0}/docs/README.md

@@ -19,6 +19,7 @@ AbstractMemory is a Python library for durable, append-only agent memory: tempor
 - FAQ: [`faq.md`](faq.md) — common questions and current limits.
 - Troubleshooting: [`troubleshooting.md`](troubleshooting.md) — symptom-oriented fixes for setup, retrieval, embedding-space, durability, and maintenance problems.
 - Development: [`development.md`](development.md) — local setup, tests, and the design backlog.
+- Architecture decisions: [`adr/README.md`](adr/README.md) — durable rules, including ADR 0001 (an altered memory ripples through the memories connected to it) and ADR 0002 (AbstractMemory owns the semantic temporal memory graph and all of its processing; applications build on it).
 
 ## Related
 

abstractmemory-0.4.0/docs/adr/0001-altered-memories-ripple.md

@@ -0,0 +1,147 @@
+# ADR 0001: An altered memory ripples through the memories connected to it
+
+Status: Accepted (operator ruling, 2026-10-21; activation model confirmed with the operator the same day).
+Amended 2026-10-27 (operator ruling): the ripple is AbstractMemory's process end to end, not a consumer's
+(ADR 0002). Aspirational: AbstractMemory does not implement it yet; AbstractNote holds a prototype
+(its ADR 0008 propagation lane) that is to be absorbed here, not kept as the implementation.
+
+## Context
+
+A memory system is not a filing cabinet. When one memory is altered, because new evidence arrived, because an
+earlier record was found, because a causal root was identified, or because a reading was revised, what we
+thought we knew about the memories connected to it is also in question. Sometimes the effect is subtle: an
+incremental refinement of a neighbour's summary. Sometimes it is dramatic: a restructuring of a whole region of
+the graph, as when a new causal root gives a deeper understanding of several things we thought we understood.
+Dramatic changes are rare in a stable system that has learned enough; in the early days of a memory system
+they happen often.
+
+Today the stores treat an alteration as local: `close_assertion`, closure records (`retract`, `supersede`,
+`reinterpreted`), reinforcement, attenuation and silencing change one record's standing or window, and the
+sleep passes (`consolidation.py`: `sleep_pass`, `consolidation_pass`, `dream_pass`, `maintenance_report`)
+tend the graph without re-evaluating the neighbours of a record whose meaning changed. Nothing in the library
+asks "given that A changed this much, what must be reconsidered about B and E?".
+
+## Decision
+
+1. **A change in a memory is an event with a magnitude, not a silent update.** Any operation that alters what a
+   memory means (its type or kind, its summary or content, its belief window, its relationships) MUST produce a
+   change record that names the memory, what changed, and a measured magnitude. The magnitude combines the
+   dimensions that matter for meaning: type change, distance between the old and new summary (an embedding
+   distance, calibrated above the writer model's own rewrite noise), the share of statements replaced, and the
+   share of relationships replaced. The thresholds live in one named place and are tuned by measurement, never
+   hard-coded in several places.
+2. **The ripple is evaluated hop by hop and decided by effect, not by distance alone.** When memory A changes,
+   every memory connected to A is a candidate for reconsideration, weighted by how much it relied on A
+   (the strength and recency of their relationship, the share of its own statements that involve A). Each
+   candidate is reconsidered; if the effect on B is minor (below the magnitude threshold once measured), the
+   ripple stops at B; if the effect on E is large, E's own change becomes a new event and the memories
+   connected to E are candidates in turn, iteratively, until no candidate's measured change clears the
+   threshold.
+3. **Propagation carries decaying impact and never amplifies.** The impact handed from A to its neighbours is the
+   measured magnitude scaled by reliance and by a decay factor; a reconsidered memory may hand on at most what it
+   received or what it measured itself, whichever is smaller; a floor stops the spread. Cycles therefore die out
+   by damping rather than by assuming the graph is a tree: the memory graph is not a DAG and the rule must not
+   require one.
+4. **Numbers choose, meaning is decided by the reader.** Magnitudes, reliance weights, decay and order select
+   which memories are reconsidered, in which order, and under what budget. What a reconsidered memory now means
+   is decided by the same reader that wrote it (a model, or the consumer's own interpretation step), never by
+   string rules on content.
+5. **Every ripple is bounded, visible and resumable.** Before a ripple runs, the system can say how many memories
+   may be reconsidered and why (the sources and their magnitudes). A ripple runs under a budget; when the budget
+   stops it, what was left is recorded and reported, never dropped silently (root framework ADR-0026). A second
+   pass over the same change, with nothing new, costs no reader call: an unchanged reconsideration is settled by
+   comparing structure, and is itself recorded.
+6. **History is kept.** A reconsidered memory keeps its previous reading in the journal; the as-received view of
+   the graph before the ripple stays answerable. Closures caused by a ripple carry their cause (the source memory
+   and the hop count) so that a later reader, human or model, can see why a belief moved.
+7. **The ripple is an activation with a threshold, not a distance rule.** Whether a connected memory is
+   reconsidered is decided by an activation function over the impact it receives: each memory accumulates the
+   reliance-weighted impacts of every changed neighbour within a pass (several small changes together can
+   cross what none crosses alone), the accumulated potential passes through a smooth gate (a logistic
+   `1 / (1 + e^-k(x - θ))` or an equivalent monotone function; the gate is a configuration, not a model), and
+   the memory is reconsidered when the gated potential is above the floor. The potential's input is a weighted
+   sum of standardised signals (type change, summary distance, statements replaced, relationships replaced),
+   each standardised against the reader's own rewrite noise, and divided by the memory's **mass** (how much
+   evidence already supports it): a thinly evidenced memory moves on little, a heavily evidenced one needs
+   more, which is how a stable system comes to ripple rarely without anyone scheduling quiet. Onward
+   propagation beyond one hop uses the **measured** change of the reconsidered memory, never the predicted
+   impact alone. Termination is guaranteed by three rules together: a memory is reconsidered at most once per
+   pass (a refractory period), impact never amplifies (loop gain `decay × max reliance × max gate slope < 1`),
+   and the floor stops the tail. Every gate decision is recorded with its potential, so thresholds can be
+   re-tuned from the record without re-running the ripple.
+8. **Edges learn.** The reliance weight of an edge may be adjusted from history: an edge whose ripples
+   repeatedly produced an unchanged reconsideration conducts less next time; an edge whose ripples produced
+   real change conducts more. Adjustments are bounded, recorded, and never silence an edge entirely.
+9. **Stable systems ripple rarely; young systems ripple often, and that is expected.** The cadence predicate of
+   the sleep pass (`maintenance_due`) and any consumer's scheduler MUST treat pending ripples as work due,
+   with priority given to the largest sources, and MUST NOT suppress ripples to keep a young system quiet.
+
+## Consequences
+
+### Positive
+- The graph says what we know *now*, with the understanding the newest evidence allows, instead of what we
+  happened to believe when each memory was first written.
+- Deep changes (a new causal root, a re-dated archive, an entity that turns out to be a person as well as a
+  project) reach the memories that leaned on them, in a bounded and explainable way.
+- Every moved belief has a cause on record.
+
+### Negative
+- Reconsideration costs reader calls; a young system pays more. Budgets and the no-call settle rule bound it,
+  and the operator sees the bound before the run.
+- Thresholds are empirical; a wrong threshold either spreads noise (too low) or freezes understanding (too
+  high). Calibration against the reader's own rewrite noise is mandatory before a threshold is trusted.
+- The journal grows: one record per reconsideration and per change event.
+
+### Neutral
+- AbstractMemory owns the whole ripple: the primitives (change records, closure causes, additive windows,
+  journal history), the propagation and activation, the budget and the reconsideration step. The reader that
+  decides what a reconsidered memory now means (decision 4) is a model the host supplies to AbstractMemory
+  (an injected reader), so the process lives here while the model choice stays with the host. Consumers
+  (AbstractNote, AbstractEntity, gateway apps) trigger and display ripples; they do not implement them.
+
+## Enforcement
+
+- A pull request that adds or changes an operation altering a memory's meaning MUST either emit a change record
+  with a magnitude or state in the ADR-linked backlog item why the operation cannot (and what the consumer must
+  do instead).
+- Closure records written because of a ripple MUST carry the cause (`source memory`, `hops`); a reviewer rejects
+  a cause-less ripple closure.
+- No code path may cap a ripple without recording what was left out (`left_out`) and warning; the marker
+  `#[WARNING:TRUNCATION]` applies to any bounded preview of a ripple's members.
+- Threshold constants live in one module with their calibration quoted; a second copy of a threshold is a
+  review failure.
+- Docs: `memory-system.md` "Sleep and dreams" MUST describe the ripple when the pass gains one; until then it
+  states that the ripple is planned in AbstractMemory (backlog 0054) and points here.
+- A consumer package MUST NOT add its own ripple, propagation or activation logic over memories; a gap in
+  AbstractMemory is raised as an AbstractMemory backlog item (ADR 0002).
+
+## Validation
+
+- Unit: a deep change spreads one hop; a shallow change does not; two sub-threshold changes on the same neighbour
+  together cross the gate; a heavily evidenced memory needs more impact than a thin one; the floor stops a hub;
+  a cycle dies within a bounded number of hops with the loop gain below one; a second pass with nothing new makes
+  no reader call; a budget stop records `left_out` equal to what is pending; every gate decision is on record with
+  its potential. Each check MUST go red when its mechanism is removed (mutation list in the test file).
+- Calibration: the summary-distance threshold is set from a measured distribution of same-memory rewrites by the
+  reader in use, and the report that set it is linked from the constants module.
+- Scenario: a dated archive that changes the type of one memory (project → person) must reconsider the memories
+  connected to it and leave unrelated regions untouched; the as-received view before the ripple still answers.
+
+## Backlog links
+
+- Proposed: [ripple_wave/0001_change_records_and_ripple_primitives.md](../backlog/proposed/ripple_wave/0001_change_records_and_ripple_primitives.md)
+  (the AbstractMemory primitives: change records with magnitude, closure causes, `maintenance_due` counting pending
+  ripples, `narrow_assertion`).
+- Planned: [knowledge_graph_convergence/0054_ripple_propagation_and_activation.md](../backlog/planned/knowledge_graph_convergence/0054_ripple_propagation_and_activation.md)
+  (the propagation, activation and reconsideration process in AbstractMemory).
+- Prototype to absorb, not to keep: AbstractNote ADR 0008 and its propagation lane (R6, 2026-10-20/21: calibrated
+  thresholds, decay 0.5, floor 0.1, one hop per pass, budgeted stage, no-call settle), see
+  `abstractnote/docs/adr/0008-interpretation-is-a-derived-view.md`, `abstractnote/untracked/briefs/R6-propagation-design.md`,
+  and AbstractNote's unmerged branch `retro/integration` (`recall/propagation.py`, `recall/activation.py`).
+
+## Related
+
+- ADR 0002 (AbstractMemory owns the semantic temporal memory graph and all its processing).
+- Root framework ADR-0026 (truncation policy: nothing silent).
+- `memory-system.md` (attention, closures, sleep and dreams), `api.md` (closure records, `close_assertion`, consolidation).
+- AbstractEntity's maintenance phases (the sleep phase where the graph is tended) as prior art for a scheduled, bounded night.

abstractmemory-0.4.0/docs/adr/0002-abstractmemory-owns-the-memory-graph.md

@@ -0,0 +1,92 @@
+# ADR 0002: AbstractMemory owns the semantic temporal memory graph and all of its processing
+
+Status: Accepted (operator ruling, 2026-10-27). Aspirational for existing consumers: AbstractNote currently
+keeps a parallel graph (its ADR 0003) that is to converge here (backlog track `knowledge_graph_convergence/`).
+
+## Context
+
+AbstractMemory is the framework's semantic, temporal memory graph: the place where notes, messages,
+documents and an entity's own experience become knowledge that structures and reorganises itself over
+time. In October 2026 AbstractNote, an application built on AbstractGateway, needed capabilities AbstractMemory
+did not offer for document knowledge (an entity registry with reversible merges, a claim lifecycle with a
+revision log, hybrid search and timelines, communities, consolidation, reflection, the ripple of ADR 0001). It
+built them inside its own package, over its own SQLite index, and kept AbstractMemory only as a write-only
+projection of its claims (AbstractNote ADR 0003), including direct writes to AbstractMemory's private tables.
+About half of AbstractNote's code is now generic memory-graph logic that no other application can use.
+
+That is the wrong direction for the framework. AbstractEntity (self-evolving persistent agents that keep
+diaries and leave notes for themselves) needs the same capabilities, and so does any assistant or agent that
+should learn from what it reads. Some of AbstractNote's designs are newer and stronger than AbstractMemory's;
+they belong in AbstractMemory so every consumer benefits, not in one application.
+
+## Decision
+
+1. **One home for memory.** Everything that structures, links, revises, consolidates, reorganises or
+   retrieves memories lives in AbstractMemory: entities and identity, claims and their lifecycle, revisions
+   and history, retrieval (search, expansion, timelines, then-versus-now), self-organisation (consolidation,
+   communities, topics), reflection and review, and the ripple of an altered memory (ADR 0001).
+2. **Consumers build on the graph; they never rebuild it.** An application or package may add an abstraction
+   on top of AbstractMemory (for example a notes or diary layer) through its public API. It must not keep a
+   parallel graph, a second store of the same knowledge, or its own copy of memory processes, and must never
+   write AbstractMemory's private tables.
+3. **A gap is fixed in AbstractMemory.** When AbstractMemory is not good enough for a consumer, the fix is an
+   AbstractMemory change (raised as an AbstractMemory backlog item), not a workaround in the consumer.
+4. **Better designs are absorbed.** A design proven in a consumer (as AbstractNote's entity registry, revision
+   log or ripple prototype) is generalised into AbstractMemory and the consumer then uses it.
+5. **The process lives here; the model is supplied.** Steps that need judgement (a model deciding identity,
+   what a revised memory means, a summary) run inside AbstractMemory's process through a reader the host
+   supplies (an injected model client or callable). Model choice and cost stay with the host; the process,
+   its bounds and its records stay in AbstractMemory.
+6. **Note-specific and agent-specific framing stays with the consumer.** Capture, file import, the wording of
+   prompts for one kind of input, and the views an application shows remain the consumer's, as long as they
+   read and write through AbstractMemory.
+
+## Consequences
+
+### Positive
+- Every application (AbstractNote, AbstractEntity, AbstractAssistant, agents) runs on one implementation of
+  memory, and improvements to memory reach all of them.
+- Knowledge captured through one app is visible to its OWNER's other apps through the gateway (and an entity's to
+  the person who owns the entity); never to another person by default: visibility is strict ownership, and a plane
+  is not a sharing scope (ADR 0003 decision 2, amended 2026-10-27).
+
+### Negative
+- AbstractMemory grows a document and world-knowledge layer beside its agent memory system, and must keep both
+  coherent.
+- AbstractNote must migrate off its parallel graph capability by capability, which is real work and
+  temporarily slows its own features.
+
+### Neutral
+- Generic infrastructure AbstractNote also built (a durable work queue with leases and retries, a memory read
+  API over HTTP) belongs to AbstractRuntime and AbstractGateway rather than here; this ADR does not decide their
+  shape.
+
+## Enforcement
+
+- Review rejects, in any consumer, access to AbstractMemory internals (`_table`, `_conn`, `_lock` or any `_`
+  attribute of a store) and any new memory-graph process (entity resolution, claim revision, consolidation,
+  communities, ripple, retrieval fusion) added outside AbstractMemory.
+- A consumer that needs a missing capability opens an AbstractMemory backlog item and links it from its own
+  backlog; the consumer item is blocked on it rather than implementing a workaround.
+- New AbstractMemory capabilities absorbed from a consumer cite that consumer's design and tests as prior art.
+
+## Validation
+
+- A search for private-attribute access to AbstractMemory objects in consumer repositories returns nothing once
+  each migration item closes (AbstractNote today: `store/kg.py`).
+- Each capability in the convergence track has a scenario test that a consumer-shaped client passes through the
+  public API alone.
+- AbstractNote's backlog shows each parallel-graph capability either migrated or with a linked AbstractMemory item.
+
+## Backlog links
+
+- Planned track: [knowledge_graph_convergence/](../backlog/planned/knowledge_graph_convergence/README.md)
+  (items 0050-0055).
+- Related: [ripple_wave/0001](../backlog/proposed/ripple_wave/0001_change_records_and_ripple_primitives.md)
+  (the ripple primitives).
+- Consumer side: AbstractNote backlog 0033-0036 (track `planned/memory_convergence/`).
+
+## Related
+
+- ADR 0001 (an altered memory ripples through the memories connected to it).
+- AbstractNote ADR 0003 (its parallel graph, now transitional) and ADR 0008 (its ripple prototype).