docs: promote verbatim-vs-derivative essay from research/ to README (#170)

jphein · claude · jphein · commit 6a264d904e80 · 2026-05-24T17:49:50.000-07:00
The verbatim-vs-derivative axis essay (docs/research/verbatim-vs-derivative-axis.md) is the fork's standalone treatment of Principle 1. Issue #170 asked for it to be elevated from a buried research/ doc to a first-class reference that external readers can find via the README. README changes: - Inline link from "What this is" → essay (replacing bare text "verbatim-vs-derivative thesis"). - Inline link from "Why this fork exists" → essay (replacing bare text "verbatim-vs-derivative axis"). - New "Sources — Synthesis and research" subsection calling out the essay by name as the standalone treatment of Principle 1, alongside the True Memory comparison, benchmark survey, and three-patterns research. Essay changes: - Two broken anchors fixed in Further reading: both pointed at README sections (#the-four-layers, #the-thesis-operational-principles) that moved to docs/ARCHITECTURE.md in the README pivot. - Body paragraph reference to "the README's thesis section" retargeted to docs/ARCHITECTURE.md for the same reason. - Last revised bumped to 2026-05-24. Closes #170. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
diff --git a/FORK_CHANGELOG.md b/FORK_CHANGELOG.md
@@ -41,6 +41,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   *Files:* `mempalace/cli.py`, `tests/test_cli_stats.py`
 
 
+### Changed
+
+
+- **Promote verbatim-vs-derivative essay from research/ to README (#170)** ([`TBD`](https://github.com/techempower-org/mempalace/commit/TBD))
+  The verbatim-vs-derivative axis essay
+  (``docs/research/verbatim-vs-derivative-axis.md``) is the
+  standalone treatment of Principle 1. Linked inline from the
+  README's "What this is" and "Why this fork exists" sections,
+  and called out by name in a new "Sources — Synthesis and
+  research" subsection alongside the True Memory comparison,
+  benchmark survey, and three-patterns research. Also fixes
+  two broken anchors in the essay's Further reading section
+  (pointed at the old README locations of "the four layers"
+  and "the thesis"; both moved to ``docs/ARCHITECTURE.md`` in
+  the README pivot) and refreshes the essay's Last-revised
+  date. Closes #170.
+
+  *Files:* `README.md`, `docs/research/verbatim-vs-derivative-axis.md`
+
+
 ## [2026-05-23]
 
 
diff --git a/README.md b/README.md
@@ -29,11 +29,11 @@
 
 A verbatim-first local AI memory system. This fork tracks `upstream/develop` through the 2026-05-23 sync (commit `eb77c8c`) and runs in production on a **335K+ drawer Postgres + pgvector + Apache AGE palace** behind [palace-daemon](https://github.com/techempower-org/palace-daemon). It carries ~507 fork-ahead commits that compose with — not replace — bensig's release direction; the v3.3.5 release (2026-05-10) includes our co-authored `_get_collection` retry-once via upstream #1377. 3009 tests pass on `main`.
 
-The fork's architectural thinking — the four-layer memory model, the verbatim-vs-derivative thesis, design principles, and the two-memory-layer pairing with Auto Dream — lives in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). The new things here are *what we've learned*, not just what we've fixed.
+The fork's architectural thinking — the four-layer memory model, the [verbatim-vs-derivative thesis](docs/research/verbatim-vs-derivative-axis.md), design principles, and the two-memory-layer pairing with Auto Dream — lives in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). The new things here are *what we've learned*, not just what we've fixed.
 
 ## Why this fork exists
 
-We surveyed the memory-system landscape in April 2026 and found no verbatim-first local system with MCP. The landscape has since fragmented — MCP memory servers proliferated in May 2026 — but the verbatim-vs-derivative axis remains the clearest architectural dividing line. Updated survey as of 2026-05-24:
+We surveyed the memory-system landscape in April 2026 and found no verbatim-first local system with MCP. The landscape has since fragmented — MCP memory servers proliferated in May 2026 — but the [verbatim-vs-derivative axis](docs/research/verbatim-vs-derivative-axis.md) remains the clearest architectural dividing line. Updated survey as of 2026-05-24:
 
 ### Verbatim-first systems
 
@@ -253,6 +253,13 @@ The full enumeration of fork-ahead changes. The canonical source is [`docs/fork-
 
 ## Sources
 
+### Synthesis and research
+
+- [**The Verbatim-vs-Derivative Axis**](docs/research/verbatim-vs-derivative-axis.md) — standalone treatment of [Principle 1](docs/ARCHITECTURE.md#1-verbatim-vs-derivative-is-the-canonical-axis). Structural argument, the April-May 2026 recovery-collection episode (210× token-budget gap closed by one structural change), and Anthropic's Dreams API as independent vendor-API ratification of the same axis.
+- [**True Memory vs MemPalace**](docs/research/2026-05-24-true-memory-comparison.md) — six-vs-four layers, benchmark comparison, convergent verbatim-first design.
+- [**Memory System Benchmarks (2026-05)**](docs/research/2026-05-24-memory-system-benchmarks.md) — LongMemEval/LoCoMo/BEAM landscape survey across 20+ systems.
+- [**Three Patterns for Agent Memory**](docs/research/three-patterns-for-agent-memory.md) — Familiar / RLM / parallel hybrid on jp-realm-v0.1; invocation as bottleneck.
+
 See [`docs/BIBLIOGRAPHY.md`](docs/BIBLIOGRAPHY.md) for the complete documentation index and external references.
 
 ## License
diff --git a/docs/fork-changes.yaml b/docs/fork-changes.yaml
@@ -24,6 +24,29 @@
 
 entries:
 
+  - id: verbatim-derivative-essay-promotion
+    date: 2026-05-24
+    bucket: Changed
+    commit: TBD
+    area: Docs
+    summary: "Promote verbatim-vs-derivative essay from research/ to README (#170)"
+    files:
+      - README.md
+      - docs/research/verbatim-vs-derivative-axis.md
+    body: |
+      The verbatim-vs-derivative axis essay
+      (``docs/research/verbatim-vs-derivative-axis.md``) is the
+      standalone treatment of Principle 1. Linked inline from the
+      README's "What this is" and "Why this fork exists" sections,
+      and called out by name in a new "Sources — Synthesis and
+      research" subsection alongside the True Memory comparison,
+      benchmark survey, and three-patterns research. Also fixes
+      two broken anchors in the essay's Further reading section
+      (pointed at the old README locations of "the four layers"
+      and "the thesis"; both moved to ``docs/ARCHITECTURE.md`` in
+      the README pivot) and refreshes the essay's Last-revised
+      date. Closes #170.
+
   - id: cli-stats-dashboard
     date: 2026-05-24
     bucket: Added
diff --git a/docs/research/verbatim-vs-derivative-axis.md b/docs/research/verbatim-vs-derivative-axis.md
@@ -4,7 +4,7 @@
 storage layer: store verbatim, derive lazily, treat every derivative as
 replaceable. Companion to the README's four-layer model and operational thesis.*
 
-Last revised: 2026-05-22.
+Last revised: 2026-05-24.
 
 ## TL;DR
 
@@ -29,7 +29,7 @@ The decision creates an asymmetric contract. **Verbatim writes must always succe
 2. **Lazy derivation.** Derivative artifacts are produced when needed (background processes, on-demand re-derivation, opt-in enrichment), not synchronously inside the write path. The write path is the drawer plus minimum unambiguous metadata (wing/room from cwd or transcript path, timestamp, content hash).
 3. **Replaceable.** Any derivative store can be dropped, rebuilt under a different algorithm, re-embedded, or re-keyed — because the verbatim record underneath is intact.
 
-The README's thesis section names this as Principle 1 ("verbatim vs. derivative is the canonical axis"). This essay is the longer argument for why the call is load-bearing, what alternatives fail at, and where the line actually sits.
+[`docs/ARCHITECTURE.md`](../ARCHITECTURE.md#1-verbatim-vs-derivative-is-the-canonical-axis) names this as Principle 1 ("verbatim vs. derivative is the canonical axis"). This essay is the longer argument for why the call is load-bearing, what alternatives fail at, and where the line actually sits.
 
 ## 2. Why derive-on-write accumulates failure modes
 
@@ -127,8 +127,8 @@ The fork's working slogan is "derivatives next to, never on top of." This essay
 
 Background on the four-layer model the axis sits inside:
 
-- [README — the four layers](../../README.md#the-four-layers) — storage / encoder / retrieval / consumption.
-- [README — the thesis](../../README.md#the-thesis-operational-principles) — Principle 1 is the README's compressed statement of the verbatim-vs-derivative axis.
+- [`docs/ARCHITECTURE.md` — the four layers](../ARCHITECTURE.md#the-four-layers) — storage / encoder / retrieval / consumption.
+- [`docs/ARCHITECTURE.md` — the thesis](../ARCHITECTURE.md#the-thesis-operational-principles) — Principle 1 is the compressed statement of the verbatim-vs-derivative axis.
 
 Adjacent fork research:
 
diff --git a/website/public/llms-full.txt b/website/public/llms-full.txt
@@ -48,11 +48,11 @@ Files included, in order:
 
 A verbatim-first local AI memory system. This fork tracks `upstream/develop` through the 2026-05-23 sync (commit `eb77c8c`) and runs in production on a **335K+ drawer Postgres + pgvector + Apache AGE palace** behind [palace-daemon](https://github.com/techempower-org/palace-daemon). It carries ~507 fork-ahead commits that compose with — not replace — bensig's release direction; the v3.3.5 release (2026-05-10) includes our co-authored `_get_collection` retry-once via upstream #1377. 3009 tests pass on `main`.
 
-The fork's architectural thinking — the four-layer memory model, the verbatim-vs-derivative thesis, design principles, and the two-memory-layer pairing with Auto Dream — lives in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). The new things here are *what we've learned*, not just what we've fixed.
+The fork's architectural thinking — the four-layer memory model, the [verbatim-vs-derivative thesis](docs/research/verbatim-vs-derivative-axis.md), design principles, and the two-memory-layer pairing with Auto Dream — lives in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). The new things here are *what we've learned*, not just what we've fixed.
 
 ## Why this fork exists
 
-We surveyed the memory-system landscape in April 2026 and found no verbatim-first local system with MCP. The landscape has since fragmented — MCP memory servers proliferated in May 2026 — but the verbatim-vs-derivative axis remains the clearest architectural dividing line. Updated survey as of 2026-05-24:
+We surveyed the memory-system landscape in April 2026 and found no verbatim-first local system with MCP. The landscape has since fragmented — MCP memory servers proliferated in May 2026 — but the [verbatim-vs-derivative axis](docs/research/verbatim-vs-derivative-axis.md) remains the clearest architectural dividing line. Updated survey as of 2026-05-24:
 
 ### Verbatim-first systems
 
@@ -272,6 +272,13 @@ The full enumeration of fork-ahead changes. The canonical source is [`docs/fork-
 
 ## Sources
 
+### Synthesis and research
+
+- [**The Verbatim-vs-Derivative Axis**](docs/research/verbatim-vs-derivative-axis.md) — standalone treatment of [Principle 1](docs/ARCHITECTURE.md#1-verbatim-vs-derivative-is-the-canonical-axis). Structural argument, the April-May 2026 recovery-collection episode (210× token-budget gap closed by one structural change), and Anthropic's Dreams API as independent vendor-API ratification of the same axis.
+- [**True Memory vs MemPalace**](docs/research/2026-05-24-true-memory-comparison.md) — six-vs-four layers, benchmark comparison, convergent verbatim-first design.
+- [**Memory System Benchmarks (2026-05)**](docs/research/2026-05-24-memory-system-benchmarks.md) — LongMemEval/LoCoMo/BEAM landscape survey across 20+ systems.
+- [**Three Patterns for Agent Memory**](docs/research/three-patterns-for-agent-memory.md) — Familiar / RLM / parallel hybrid on jp-realm-v0.1; invocation as bottleneck.
+
 See [`docs/BIBLIOGRAPHY.md`](docs/BIBLIOGRAPHY.md) for the complete documentation index and external references.
 
 ## License
