@ssheleg/agent-stack 0.14.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## v0.16.0 — the whole survey, not just its taxonomy
+
+v0.15.0 took the taxonomy and the named failure modes. This takes the rest: the write
+path and the landscape, as two references under the spine that already exists.
+
+- **`memory-lifecycle.md` — how an entry is made, changed and thrown away.** Five formation
+  operations with the cost of each stated rather than implied: semantic summarization is
+  *lossy by design* and wrong for evidence-critical tasks; structured construction buys
+  multi-hop and pays schema rigidity; latent is a black box; parametric cannot be precisely
+  removed. Summarization's two shapes fail differently — incremental drifts because each
+  summary is built from the last, partitioned loses cross-partition dependencies — and
+  **summarizing by fixed window is partitioned summarization with the worst partition rule**.
+- **Updating is not consolidation.** One resolves conflict, the other abstracts, and a
+  system needs both. The field's own trajectory is worth copying rather than rediscovering:
+  early systems deleted the superseded entry and broke temporal continuity; the better
+  pattern is **temporal annotation** — mark a validity window instead — which also makes the
+  stability–plasticity decision reversible, and it has no general answer.
+- **Consolidation has a cost this pack did not state**: it risks information smoothing, and
+  the outlier it smooths away is often the entry worth keeping.
+- **`memory-landscape.md` — build or adopt, measure, and what is not practice yet.** Around
+  twenty-five open-source frameworks give you an index and leave you the judgement: what
+  becomes a memory, when to retrieve, what to abstain on, what to demote. **Adopt for the
+  index, not for the judgement.** Frameworks are compared by the axes that separate them
+  rather than by a list that expires.
+- Benchmarks are split into memory-oriented and long-horizon-that-stresses-memory, and the
+  first question is neither: it is `agent-evals`' question — **what fails if memory is
+  silently disabled?** A memory never queried and a memory that is empty score identically
+  on every benchmark; only the retrieval log separates them.
+- Frontiers are marked as frontiers, with one exception acted on: **expose memory operations
+  as tools the agent calls.** It makes every memory decision legible in the trace, including
+  the decision NOT to retrieve — which is the silent failure this whole subject is about,
+  and which a background memory module cannot show you.
+- Three things the pack deliberately does NOT implement are named as absent rather than
+  quietly added: frequency-based forgetting, temporal annotation, dual-phase updating. Each
+  is a real change to a mechanism in production, and a reference's job is to say what the
+  options are, not to rewrite `patterns.md` from a survey.
+- The citation now has **one home**. The member's own validator refused three files each
+  repeating the pinned source — "a fact with two homes disagrees with itself on the first
+  edit" — so the spine holds it and the siblings name it.
+
+## v0.15.0 — memory architecture, and the axes the layer table does not have
+
+- **`agent-orchestrator/references/memory-architecture.md`** — form, function and dynamics
+  as the three axes of a memory decision, with the layer table demoted to what it is: one
+  property of the answer. Source pinned with a read date — *Memory in the Age of AI Agents:
+  A Survey*, arXiv:2512.13564v2, 13 Jan 2026, read 2026-08-27.
+- **Retrieval was two mentions across 1,938 lines of references**, and it is four decisions:
+  whether to retrieve at all and from which store, what query to retrieve with, which
+  strategy runs the search, what reaches the prompt. The first is the one nobody
+  instruments — an agent that overestimates its own knowledge and skips retrieval answers
+  confidently from nothing, with **no error, no empty result and no latency spike**.
+- **Facts are now separated from experience, and by entity.** Layers 3 and 4 are
+  experiential; nothing in them is a factual store. A stale fact about the USER makes the
+  agent rude, a stale fact about the ENVIRONMENT makes it wrong — one expiry rule for both
+  is wrong twice.
+- **Forgetting gains the long-tail trap.** Frequency-based eviction is the easy policy and
+  the one that deletes the rarely-read entry preventing the rare expensive mistake. Where
+  storage is not the binding constraint: demote, not delete.
+- Also carried: forms beyond token-level and what each costs (parametric memory cannot be
+  selectively deleted; latent memory cannot be inspected), why `agent-sync`'s leases are
+  coordination rather than shared memory, and abstention under low-confidence retrieval —
+  which needs a similarity floor, because semantic search always returns K results and an
+  empty store looks identical to an irrelevant one.
+- **§7 was split rather than trimmed.** The house auditor refused the first attempt at
+  4981 tokens against a 4750 working limit and named the remedy itself. The context-budget
+  trap, layer 0 carryover and workspace scale moved into the new reference; the body is now
+  **4659 tokens — below the 4708 it sat at before any of this**.
+- Discoverability, measured: against *"agent memory architecture: forms, functions,
+  dynamics, retrieval, forgetting"* this skill ranked **8th** among installed skills and now
+  ranks **1st**. The description is 965 chars, inside the 970-char working limit.
+
 ## v0.14.1 — the workforce axis: provider lifecycle and workspace-scale memory
 
 (v0.14.0 was burned during release engineering: its tag landed on a commit a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-stack",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "scripts": {
     "test": "python3 test/validate.py && python3 test/plant_guard_test.py"
   },

package/plugins/agent-stack/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "agent-stack",
   "displayName": "Agent Stack",
   "description": "Two skills: agent-orchestrator — tool-calling loops, multi-stage pipelines with checkpoints, provider routing with fallback, four-layer memory, context engineering, plus the wallet side of reselling LLM access; and agent-evals — run/trace/thread evals, judges, and fixtures grown from production.",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/agent-stack/skills/agent-orchestrator/SKILL.md

@@ -3,8 +3,8 @@ name: agent-orchestrator
 description: >-
   Use when building an agent system — an orchestrator, an LLM-powered tool, a chatbot with tool
   use, an AI pipeline — or metering and billing the LLM access it burns. Covers tool-calling
-  loops, pipelines with human checkpoints, provider routing with fallback/retry, four-layer
-  memory with confidence decay, context budgets, sub-agent coordination, error hierarchies; the
+  loops, pipelines with human checkpoints, provider routing with fallback/retry, memory
+  architecture, retrieval and decay, context budgets, sub-agent coordination, error hierarchies; the
   work as a graph — parallel layers, fake edges, a checker before convergence; for resale:
   tiered wallets, one markup boundary, two-phase commit across database and provider API,
   spend-delta polling, budget and loop guards, per-tenant keys. Triggers - "agent",
@@ -232,23 +232,22 @@ Four layers, each with a different lifetime and a different reason to exist:
 | 3 Long-term learnings | per resource | months | what worked, with a confidence score |
 | 4 Insights | per project | permanent | conclusions that outlived their resource |
 
-Read `references/patterns.md` for the data models, **Confidence Management**
-(how a learning decays and when it is retired), **Learning Extraction
-Heuristics**, **Fuzzy Deduplication** and **Conflict Resolution** — the four
-mechanisms that decide what actually enters layers 3 and 4.
-
-**The trap is the budget, not the storage.** Every layer competes for the same
-context window, so allocation has to be decided per call rather than per layer:
-a session that trims chat history to fit a large set of learnings has quietly
-chosen old generalities over what the user said sixty seconds ago. Give layer 1
-a floor.
-
-**Layer 0 — carryover state.** Goal, artifacts, verified work and restrictive
-mode cross a compaction boundary as copied typed blocks, not prose (§12).
-
-**Workspace scale.** Managing persistent workspaces rather than sessions shifts
-the scopes — run, workspace, global, doctrine — and adds the journal-spine
-rules: `references/patterns.md` → **Workspace-scale memory**.
+What enters layers 3 and 4 is decided by `references/patterns.md` — **Confidence
+Management**, **Learning Extraction Heuristics**, **Fuzzy Deduplication**, **Conflict
+Resolution**.
+
+**These four are lifetimes, and lifetime is not the taxonomy.** Layers 3 and 4 are
+*experiential*; **nothing here is a factual store**, and a stale fact about the USER makes
+the agent rude while one about the ENVIRONMENT makes it wrong. Retrieval is absent here and
+is four decisions, the first of which — whether to retrieve at all — fails as a confident
+answer built from nothing, in no error log.
+
+**Design a memory layer from
+[`references/memory-architecture.md`](references/memory-architecture.md)**, not from this
+table — it also carries the context-budget trap, layer 0 carryover and workspace scale.
+The write path is [`references/memory-lifecycle.md`](references/memory-lifecycle.md);
+what to build on and measure with is
+[`references/memory-landscape.md`](references/memory-landscape.md).
 ## 8. Self-Learning Feedback Loops
 
 Three cycles feed the memory layers, and they differ by what supplies the signal: a failed

package/plugins/agent-stack/skills/agent-orchestrator/references/memory-architecture.md

@@ -0,0 +1,326 @@
+# Memory architecture — deciding what the agent remembers before deciding where to put it
+
+**Load this when** an agent is being given memory for the first time, when an existing
+memory layer is being extended, or when memory is present and behaving badly — recall that
+misses, a store that grows without bound, an agent confidently answering from nothing.
+
+**Spec pinned:** *Memory in the Age of AI Agents: A Survey — Forms, Functions and
+Dynamics*, Hu et al., `https://arxiv.org/abs/2512.13564` (arXiv:2512.13564v2, 13 Jan 2026;
+NUS / RUC / Fudan / PKU / NTU and others) · read 2026-08-27. Paper list:
+`https://github.com/Shichun-Liu/Agent-Memory-Paper-List`.
+
+`SKILL.md` §7 owns the four **layers** and their lifetimes, and §8 the loops that feed
+them. Both answer *how long does this live*. **This file is upstream of that**: it decides
+what kind of memory is being built at all, and lifetime is one property of the answer
+rather than the taxonomy. The survey's own position, and the reason this file exists:
+*"traditional taxonomies such as long/short-term memory have proven insufficient to capture
+the diversity and dynamics of contemporary agent memory systems."*
+
+## Contents
+
+- [The source, and what this file adds](#the-source-and-what-this-file-adds)
+- [1. Three axes, and lifetime is not one of them](#1-three-axes-and-lifetime-is-not-one-of-them)
+- [2. Form — what physically carries it](#2-form--what-physically-carries-it)
+- [3. Function — what it is for](#3-function--what-it-is-for)
+- [4. Dynamics — formation, evolution, retrieval](#4-dynamics--formation-evolution-retrieval)
+- [5. Retrieval is four decisions, not one](#5-retrieval-is-four-decisions-not-one)
+- [5.5 The budget, layer 0, and workspace scale](#55-the-budget-layer-0-and-workspace-scale)
+- [6. Forgetting, and the long-tail trap](#6-forgetting-and-the-long-tail-trap)
+- [7. Shared memory when there is more than one agent](#7-shared-memory-when-there-is-more-than-one-agent)
+- [8. Trustworthy memory](#8-trustworthy-memory)
+- [9. What this pack does NOT claim](#9-what-this-pack-does-not-claim)
+- [10. The checklist](#10-the-checklist)
+- [11. The rest of it](#11-the-rest-of-it)
+
+## The source, and what this file adds
+
+The survey is a map of published work, not a build guide: it classifies roughly two
+hundred systems and states open problems. What is taken from it here is the **taxonomy and
+the named failure modes**, because those are what an architect needs before writing a
+schema. What is added is the decision order — form, then function, then dynamics — and the
+wiring to what this pack already owns: §7's layers, §8's learning loops, `patterns.md`'s
+confidence arithmetic, `context-engineering.md`'s budget, and `agent-evals` for judging
+whether any of it helped.
+
+**Where the survey and this pack disagree, the pack says so rather than quietly adopting.**
+§7's four layers are a *deployment* shape that has survived contact with real systems; the
+survey's three functions are an *analytical* shape. They are not rivals — the mapping is in
+§3 below — and a schema built from either alone is missing what the other sees.
+
+## 1. Three axes, and lifetime is not one of them
+
+Every memory decision is three independent questions. Answer them in this order; answering
+the third first is how a vector store arrives before anyone has said what it holds.
+
+| Axis | The question | Answered in |
+|---|---|---|
+| **Form** | what physically carries it | §2 |
+| **Function** | what it is FOR | §3 |
+| **Dynamics** | how it is formed, evolved and retrieved | §4, §5, §6 |
+
+Long-term and short-term are **not** a fourth axis. They are a consequence: the survey's
+formulation is that short- and long-term effects *"emerge not from discrete architectural
+modules but from the temporal patterns with which formation, evolution and retrieval are
+engaged."* A single store read once per task behaves as short-term; the same store read
+across tasks behaves as long-term. Design the patterns, and the lifetimes follow.
+
+## 2. Form — what physically carries it
+
+Three realizations. Most agent work uses the first and never learns the other two exist,
+which is fine until the first one's costs bite.
+
+| Form | What it is | Reach for it when | What it costs |
+|---|---|---|---|
+| **Token-level** | text, key-value, documents, graphs — anything the model reads as tokens | almost always; it is legible, auditable and editable by hand | every read spends context, and the store competes with the task for the window |
+| **Parametric** | the knowledge is in weights — fine-tuning, model editing, adapters | a behaviour must hold with no retrieval step and no context cost, and it changes rarely | not auditable, not selectively deletable, and **wrong entries are expensive to remove** — which collides with §8's right to be forgotten |
+| **Latent** | compressed internal states — KV reuse, latent tokens | throughput or privacy dominates and the content need not be read by a person | opaque: nobody can inspect what it holds, so a defect in it is invisible until behaviour is wrong |
+
+Token-level splits further by structure — flat (1D), planar/tabular (2D), hierarchical or
+graph (3D). Structure is a **retrieval** decision, not a storage one: a graph is worth its
+cost when queries are multi-hop, and is overhead when they are lookups.
+
+**The default, stated so it is a choice and not an accident:** token-level, flat, until a
+measured retrieval failure justifies structure. Structure added before that is a schema
+maintained for a query nobody runs.
+
+## 3. Function — what it is for
+
+Three pillars. The name matters because **the update rule and the trust level differ per
+pillar**, and a store that mixes them applies one rule to all three.
+
+| Function | Answers | Subtypes | Update rule |
+|---|---|---|---|
+| **Factual** | *what does the agent know* | **user** facts (identity, stable preferences, task constraints, commitments) · **environment** facts (document state, resource availability, what other agents can do) | corrected on contradiction; the newest assertion usually wins |
+| **Experiential** | *how does the agent improve* | case-based (whole solutions and trajectories) · strategy-based (insights, workflows, patterns) · skill-based (functions, code, tools it wrote) | earned from a **contrast** — see §8 of `SKILL.md`; never from a single success |
+| **Working** | *what is it thinking about now* | single-turn (input condensation, observation abstraction) · multi-turn (state consolidation, hierarchical folding) | discarded at the task boundary unless promoted |
+
+**The split this pack was missing, and why it matters.** §7's layers do not separate *user*
+facts from *environment* facts, and the two have opposite failure modes. A user fact that
+goes stale makes the agent **rude** — it addresses a person by a preference they abandoned.
+An environment fact that goes stale makes the agent **wrong** — it acts on a file that
+moved, a budget that was spent, a tool that was removed. So environment facts need a
+freshness policy and a re-check on use; user facts need a correction path and a way for the
+person to see and edit what is held about them. One TTL for both is wrong twice.
+
+**Mapping to §7's layers**, so the two shapes can be held at once:
+
+| §7 layer | Function it actually serves |
+|---|---|
+| 1 Chat history | working, multi-turn |
+| 2 Working memory (per resource) | working promoted to factual-about-this-task |
+| 3 Long-term learnings | experiential — strategy-based |
+| 4 Insights | experiential — strategy-based, cross-resource |
+| *(missing)* | **factual: user and environment** — add it as its own store, not as a learning |
+
+## 4. Dynamics — formation, evolution, retrieval
+
+Three operators, and a system is defined by which of them it runs and how often.
+
+- **Formation** — what becomes a memory candidate at all. Selective, never the whole
+  transcript: *"extracting information with potential future utility rather than storing
+  the entire interaction history verbatim."* Owned here by §8 and
+  `patterns.md` → **Learning Extraction Heuristics**.
+- **Evolution** — consolidation, updating, forgetting. Owned by `patterns.md` →
+  **Confidence Management**, **Fuzzy Deduplication**, **Conflict Resolution**. Forgetting is
+  under-specified there; §6 below closes it.
+- **Retrieval** — this pack had almost nothing on it. §5 is the whole of it.
+
+## 5. Retrieval is four decisions, not one
+
+*"Memory retrieval is not a static search operation but a dynamic cognitive process."* Four
+stages, in execution order. A system that implements only the third — the usual case — is
+running one of four.
+
+### 5.1 Timing and intent — whether to retrieve at all, and from which store
+
+**The failure this stage exists to prevent has a name and it is silent.** When an agent
+overestimates its own knowledge and does not retrieve, there is no error, no empty result
+and no latency spike — there is a confident answer built from nothing. It is invisible to
+every health check that watches for failures.
+
+- **Always-on retrieval** is the safe default and it is not free: it spends context on
+  every turn and injects noise into questions that needed none.
+- **Model-decided** retrieval is cheaper and introduces exactly the silent mode above.
+- **Fast–slow** is the compromise worth the wiring: answer, self-assess, and retrieve
+  deeper only when the first answer is judged insufficient.
+
+**Instrument it or do not ship it.** Log retrieval decisions including the negatives —
+*asked, decided not to retrieve* — and give `agent-evals` a fixture where the answer is
+only obtainable from memory. A memory that is never queried scores the same as a memory
+that is empty, and only the log tells them apart.
+
+### 5.2 Query construction — what to retrieve with
+
+The user's words are not a good query against your index, and this stage is the one most
+often skipped entirely. Two techniques, and they compose:
+
+- **Decomposition** — break a compound question into sub-queries, retrieve per part.
+  Use when the question spans several facts that no single entry holds.
+- **Rewriting** — restate the query in the index's own language, or generate a hypothetical
+  answer and search with *that* (HyDE). Use when user phrasing and stored phrasing diverge
+  — which is most of the time for a store written by the agent itself.
+
+### 5.3 Strategy — how the search runs
+
+| Strategy | Strong at | Weak at |
+|---|---|---|
+| **Lexical** (BM25, TF-IDF) | exact identifiers, tool names, error strings, precision | paraphrase, synonyms |
+| **Semantic** (embeddings) | paraphrase, fuzzy match — the usual default | drift and forced top-K, which return *something* however irrelevant |
+| **Graph** | multi-hop, relational, temporal constraints | cost, and a schema to maintain |
+| **Hybrid** | lexical precision plus semantic reach | two systems to tune |
+
+**Semantic-only retrieval always returns K results.** There is no "nothing matched" unless
+a similarity floor is set, so an empty store and an irrelevant store look identical to the
+model. Set the floor, and make "nothing relevant" a value the caller can act on.
+
+### 5.4 Post-retrieval — what actually reaches the prompt
+
+Raw hits are redundant, stale and mutually contradictory. Two operations:
+
+- **Re-rank and filter** — drop low-relevance and expired items. Temporal validity is a
+  filter, not a tiebreak: a fact with a validity window that has closed is wrong, not
+  merely old.
+- **Aggregate and compress** — merge duplicates and reconstruct one coherent context.
+
+This is where `context-engineering.md`'s budget applies. §7's warning holds at every stage:
+every layer competes for one window, so give working memory a floor or a large set of old
+generalities will quietly evict what the user said a minute ago.
+
+## 5.5 The budget, layer 0, and workspace scale
+
+Moved here from `SKILL.md` §7 when that file reached its body budget: these are memory
+*architecture*, and this is the file about it.
+
+**The trap is the budget, not the storage.** Every layer competes for the same context
+window, so allocation is decided per call rather than per layer. A session that trims chat
+history to fit a large set of learnings has quietly chosen old generalities over what the
+user said sixty seconds ago. **Give layer 1 a floor.** This is the same window
+`context-engineering.md` governs, and §5.4's post-retrieval stage is where a retrieval
+that ignores it does its damage.
+
+**Layer 0 — carryover state.** Goal, artifacts, verified work and restrictive mode cross a
+compaction boundary as copied typed blocks, not prose (`SKILL.md` §12). It is a memory
+layer whose whole job is surviving one specific event.
+
+**Workspace scale.** Managing persistent workspaces rather than sessions shifts the scopes
+— run, workspace, global, doctrine — and adds the journal-spine rules:
+`patterns.md` → **Workspace-scale memory**.
+
+## 6. Forgetting, and the long-tail trap
+
+Three policies, and they are orthogonal — a system usually needs more than one:
+
+- **Time-based decay** — natural aging. `patterns.md` → Confidence Management.
+- **Frequency-based** — LRU/LFU, evict what is not read.
+- **Importance-driven** — score on temporal, frequency and semantic signals together, and
+  increasingly let a model judge salience rather than a counter.
+
+**The trap, stated because frequency-based forgetting is the easy one to reach for:**
+LRU-style eviction *"may eliminate long-tail knowledge, which is seldom accessed but
+essential for correct decision-making."* The rarely-read entry is often the one that
+prevents a rare and expensive mistake — the incident, the exception, the one customer whose
+setup differs. **When storage is not the binding constraint, do not delete: demote.** Move
+it out of the default retrieval path and keep it reachable by explicit query.
+
+Deletion is also a **correctness** operation, not only a capacity one — see §8.
+
+## 7. Shared memory when there is more than one agent
+
+The progression, and both ends are wrong:
+
+- **Isolated memories with message passing** — no interference, but redundancy, fragmented
+  context and communication overhead that grows with team size.
+- **A naive global store** — every agent reads and writes one space. This buys joint
+  attention and costs **memory clutter, write contention, and no role- or permission-aware
+  access control**.
+
+**What this pack already has, and what it is not.** `agent-sync` gives leases, race-free id
+reservation and a run journal: it decides *who may write this file right now*. That is
+coordination, and it is not shared memory — it says nothing about what an agent should be
+allowed to *read*, or whose experiential memory is trustworthy enough to act on. An agent
+system that needs both needs both.
+
+**The design rule:** make shared writes **attributed and scoped**. An entry carries who
+wrote it and under what role, and a reader may weigh it accordingly. Unattributed shared
+memory means one agent's wrong conclusion becomes every agent's premise, with nothing in
+the record to trace it back.
+
+## 8. Trustworthy memory
+
+Three pillars, and the survey's position is that these stop being features and become
+requirements once an agent is deployed and persistent.
+
+**Privacy.** Agent memory holds user-specific, persistent and potentially sensitive content
+— a different risk class from a document index. Memory modules have been shown to **leak
+private data through indirect prompt injection**: text the agent read becomes text the
+agent stored becomes text the agent will repeat. Three controls: do not store what the task
+does not need (the same rule `error-tracking` applies before events reach a third party),
+scope reads, and make **verifiable forgetting** possible — which is exactly what parametric
+memory (§2) cannot offer, and the strongest argument for keeping deletable knowledge in
+token-level form.
+
+**Explainability.** *"Users and developers still lack tools to trace which memory items
+were retrieved, how they influenced generation, or whether they were misused."* Minimum
+bar, and it is cheap if built in from the start: every retrieval is logged with the ids it
+returned, and every answer that used memory can name the entries it used. Retrofitted, it
+is a rewrite.
+
+**Hallucination robustness.** The point of memory is fewer invented answers, and a memory
+layer can add them: a confidently retrieved stale entry is worse than an empty store,
+because it carries authority. **Abstention under low-confidence retrieval** — say *"I do not
+have this"* rather than answer from the best of a bad set — is the single highest-value
+behaviour here, and it needs the similarity floor from §5.3 to be expressible at all.
+
+## 9. What this pack does NOT claim
+
+Named so a reader does not take this file for more than it is:
+
+- **No benchmark numbers are reproduced here.** The survey tabulates benchmarks (LoCoMo,
+  LongMemEval, MemBench, StreamBench and others, §6.1); which of them fits a given system
+  is an `agent-evals` question and none of them is quoted as a result.
+- **The frontier sections are frontiers.** RL-trained memory management, latent/generative
+  memory, and offline consolidation are stated in the survey as open directions, not
+  settled practice. They are in §2 as forms with costs, and nothing here recommends
+  building on them.
+- **This file was written from the survey, not from running these systems.** Where the pack
+  has its own measured experience — §7's layers, `patterns.md`'s confidence arithmetic —
+  that is marked as the pack's and is not attributed to the paper.
+
+## 10. The checklist
+
+Before an agent gets memory, answer these. An unanswered row is a decision that will be
+made by accident:
+
+1. **Which functions does it need?** Factual-user, factual-environment, experiential,
+   working — name each one you are building. Not all four are always needed; the ones you
+   skip should be skipped on purpose.
+2. **What form carries each?** Default token-level and flat. Any other answer names the
+   cost it is paying for (§2).
+3. **What forms a memory?** The contrast rule for experiential (§8 of `SKILL.md`); an
+   explicit write path for factual. Never "log the transcript".
+4. **When is it retrieved, and is that decision logged — including the negatives?** (§5.1)
+5. **What is the query?** Raw user text is the answer only if you have checked it works.
+   (§5.2)
+6. **Is there a relevance floor, so "nothing relevant" is expressible?** (§5.3)
+7. **What expires, what decays, what is demoted rather than deleted?** (§6)
+8. **If more than one agent writes it: who wrote this entry, under what role?** (§7)
+9. **Can a person see, correct and delete what is held about them?** (§8)
+10. **What eval fails if memory is silently disabled?** If none, the memory layer is
+    unmeasured and its value is a belief. (`agent-evals`)
+
+## 11. The rest of it
+
+This file is the decision spine and it deliberately stops at decisions. Two siblings carry
+the depth, both pinned to the same survey and the same read date:
+
+- [`memory-lifecycle.md`](memory-lifecycle.md) — the **write path**. Five ways to turn
+  experience into an entry and how each one fails, consolidation at three granularities,
+  why temporal annotation beats deletion when a fact is superseded, dual-phase updating,
+  and the three forgetting policies. It ends with a table of what this pack already
+  implements and three things it deliberately does not.
+- [`memory-landscape.md`](memory-landscape.md) — **build or adopt**, the axes that actually
+  separate the twenty-odd open-source memory frameworks, which benchmarks measure what, and
+  which frontier ideas are directions rather than practice. Its last section is the one
+  frontier worth acting on now: exposing memory operations as tools the agent calls, which
+  makes every memory decision visible in the trace — including the decision not to
+  retrieve.

package/plugins/agent-stack/skills/agent-orchestrator/references/memory-landscape.md

@@ -0,0 +1,128 @@
+# Memory landscape — what exists to build on, what to measure with, where it is going
+
+**Load this when** deciding whether to build a memory layer or adopt one, choosing what to
+evaluate it against, or judging whether a technique somebody is proposing is settled
+practice or a research direction.
+
+**Source:** the survey pinned in [`memory-architecture.md`](memory-architecture.md)
+— §6 resources, §7 positions and frontiers. That file is its one home; repeating the citation here would give it two.
+
+**Read the dates on everything here.** This is the fastest-moving part of the subject, and
+a landscape file is stale the day after it is written. What does not go stale is the
+*shape*: which axes the frameworks differ on, and which of the frontier ideas is a
+direction rather than a practice.
+
+## Contents
+
+- [1. Build or adopt](#1-build-or-adopt)
+- [2. Frameworks, by what actually separates them](#2-frameworks-by-what-actually-separates-them)
+- [3. Evaluating a memory layer](#3-evaluating-a-memory-layer)
+- [4. Frontiers — and which of them is not practice yet](#4-frontiers--and-which-of-them-is-not-practice-yet)
+- [5. The one that changes how you build today](#5-the-one-that-changes-how-you-build-today)
+
+## 1. Build or adopt
+
+An ecosystem of open-source memory frameworks exists — the survey tabulates around
+twenty-five, including MemGPT, Mem0, Memobase, MemoryOS, MemOS, Zep, LangMem, Cognee,
+Memary, MIRIX, and vector stores used as memory (Pinecone, Chroma, Weaviate).
+
+**What most of them give you** is storage plus retrieval: a vector or graph database, an
+API, a short/long-term split. **What most of them leave to you** is the part that decides
+whether the memory works — *"they often leave agent behavior and evaluation protocols to
+the application."*
+
+So the honest framing of the choice:
+
+| | Adopting a framework | Building on your own store |
+|---|---|---|
+| You get | schema, indexing, retrieval, a short/long split | nothing you did not write |
+| You still own | formation policy, what enters at all, forgetting policy, retrieval timing, **evals** | the same list |
+| Argues for it | not writing an index; graph or temporal support you would not build | your entries are few and structured, and a table plus a query is genuinely enough |
+
+**The decision is usually smaller than it looks.** The parts that go wrong — deciding what
+becomes a memory, when to retrieve, what to abstain on, what to demote — are yours in both
+columns. Adopt for the index, not for the judgement.
+
+## 2. Frameworks, by what actually separates them
+
+Rather than a list that expires, the axes that distinguish them — check a candidate on
+these:
+
+- **Does it model experiential memory, or only factual?** Several store facts well and have
+  no notion of a strategy learned from a trajectory. If the agent is supposed to improve,
+  this is the axis that matters.
+- **What is the structure?** Hierarchical short/long-term, graph, temporal knowledge graph,
+  flat vectors, profile-based. This decides which queries are cheap. (§3 of
+  `memory-architecture.md`.)
+- **Is temporal validity first-class?** A store that can express *"this was true until
+  March"* supports soft updating; one that cannot will make you delete history to stay
+  correct.
+- **Does it report results on memory benchmarks at all?** Most do not. Absence is not
+  failure, but a framework with published LoCoMo or LongMemEval numbers has at least been
+  measured by someone.
+- **Multimodal?** Most are text-only. The survey is explicit that **no system provides
+  truly omnimodal support** yet.
+
+## 3. Evaluating a memory layer
+
+The survey groups benchmarks two ways, and the split is the useful part.
+
+**Memory-oriented** — built to test memory directly. `LoCoMo` and `LongMemEval` are the two
+most frequently reported and the closest thing to a common yardstick. `PersonaMem`,
+`PrefEval`, `MemoryBank`, `PerLTQA`, `MPR` stress user modelling and preference tracking.
+`StreamBench`, `LifelongAgentBench`, `MemoryAgentBench`, `Evo-Memory` test lifelong and
+self-evolving behaviour — new information arriving while old information becomes obsolete
+or conflicting. `HaluMem` targets memory-induced hallucination specifically.
+
+**Long-horizon agent benchmarks that stress memory implicitly** — `SWE-Bench Verified`,
+`GAIA`, `WebArena`, `ToolBench`, `ALFWorld`. Memory is not the measured target, but
+performance depends on it.
+
+**Which to use is not the first question.** The first question is the one `agent-evals`
+asks: **what fails if memory is silently disabled?** A public benchmark measures a system
+against a distribution that is not yours. A fixture built from your own traces, where the
+answer is obtainable *only* from memory, catches the failure mode this whole subject is
+about — the agent that skips retrieval and answers confidently from nothing
+(`memory-architecture.md` §5.1). Build that fixture first; reach for a public benchmark
+when you need to compare against somebody else's system.
+
+**Instrument the negatives.** A memory never queried and a memory that is empty score
+identically on every benchmark. Only the retrieval log separates them.
+
+## 4. Frontiers — and which of them is not practice yet
+
+Marked plainly, because the risk with a survey's frontier section is building on a
+direction as though it were a technique.
+
+| Frontier | State | What it would change |
+|---|---|---|
+| **Memory generation** (over retrieval) | direction | memory synthesized on demand for the current task rather than fetched and concatenated. Two shapes: *retrieve-then-generate*, which is buildable now and is essentially §5.4 post-retrieval taken seriously; and *direct generation* with no retrieval step, which is research |
+| **Automated memory management** | early | the agent reasons about its own memory through **explicit tool calls** — add/update/delete/retrieve as actions in its loop rather than a module beside it. See §5 |
+| **RL-driven memory** | research | the progression is RL-free → RL for selected operations (reranking, the write policy) → fully learned. Most production systems are and will remain RL-free |
+| **Multimodal memory** | partial | vision is furthest along, audio underexplored, and **no omnimodal system exists** |
+| **Shared memory for multi-agent** | early | from isolated stores with message passing, through naive global stores, toward **role- and trust-aware** access. `memory-architecture.md` §7 |
+| **Trustworthy memory** | **requirement, not frontier** | privacy, explainability, hallucination robustness. `memory-architecture.md` §8 |
+| **Offline consolidation** ("sleep") | direction | a dedicated interval to reorganize, prune and replay, away from latency constraints. The buildable half of it is the **dual-phase update** in `memory-lifecycle.md` §4 |
+
+## 5. The one that changes how you build today
+
+Of everything above, **automated memory management via explicit tool calls** is the item
+worth acting on now, and it costs little.
+
+Instead of a memory module that runs beside the agent — summarizing on a timer, evicting on
+a policy, retrieving on every turn — expose memory operations as **tools the agent calls**:
+`memory.search`, `memory.write`, `memory.update`, `memory.forget`. Three consequences, and
+they are what make it worth doing rather than an aesthetic preference:
+
+1. **The decisions become legible.** Every memory operation is a tool call in the trace,
+   which means `agent-evals` can judge them and the retrieval log from
+   `memory-architecture.md` §5.1 exists for free — including the negatives, because a turn
+   with no `memory.search` call is visibly a turn that chose not to retrieve.
+2. **The agent can reason about them** — retrieve, find it insufficient, decompose and
+   retrieve again, which is the fast–slow pattern that the timing stage needs anyway.
+3. **They inherit everything the tool layer already has** — descriptions the model can act
+   on (`agent-harness`), error hierarchies, budgets and loop guards (`SKILL.md` §2).
+
+**The cost, so it is a choice:** more model calls, and a model that can decline to use
+memory at all. That second one is the silent failure mode again, which is why point 1
+matters — with tool calls you can *see* it happen, and with a background module you cannot.

package/plugins/agent-stack/skills/agent-orchestrator/references/memory-lifecycle.md

@@ -0,0 +1,154 @@
+# Memory lifecycle — how an entry is made, changed and thrown away
+
+**Load this when** writing the code that decides what becomes a memory, how a new entry
+meets the ones already there, and what leaves. `memory-architecture.md` decides *what kind*
+of memory is being built and owns retrieval; this file is the **write path**.
+
+**Source:** the survey pinned in [`memory-architecture.md`](memory-architecture.md)
+— §5.1 formation, §5.2 evolution. That file is its one home; repeating the citation here would give it two.
+
+The three operators run at **different frequencies**, and that is the design. Formation can
+run per turn, evolution per task boundary or offline, retrieval per call. Short- and
+long-term behaviour is a consequence of those frequencies, not of separate boxes.
+
+## Contents
+
+- [1. Formation — five ways to turn experience into an entry](#1-formation--five-ways-to-turn-experience-into-an-entry)
+- [2. Choosing among them](#2-choosing-among-them)
+- [3. Evolution — consolidation](#3-evolution--consolidation)
+- [4. Evolution — updating, and the stability–plasticity dilemma](#4-evolution--updating-and-the-stabilityplasticity-dilemma)
+- [5. Evolution — forgetting](#5-evolution--forgetting)
+- [6. What this pack already implements](#6-what-this-pack-already-implements)
+
+## 1. Formation — five ways to turn experience into an entry
+
+*"Instead of passively logging all interaction history, the memory system selectively
+identifies information with long-term utility."* Five operations, and they compose — one
+system commonly runs several.
+
+| Operation | What it produces | Strength | The cost, stated |
+|---|---|---|---|
+| **Semantic summarization** | a compact narrative of a long stream | drastically shorter context; ideal for long dialogue | **lossy by design** — specific details and subtle cues get smoothed out, so it is wrong for evidence-critical tasks |
+| **Knowledge distillation** | discrete reusable facts or strategies | fine-grained, function-specific | produces flat units with no relation between them |
+| **Structured construction** | a graph or tree — entities, relations, hierarchy | explainability and multi-hop queries | **schema rigidity**; extraction and maintenance cost is high, and nuance that does not fit the schema is lost |
+| **Latent representation** | vectors or KV states | high density, cross-modal, no decoding loss | **a black box** — cannot be inspected, edited or verified by a person |
+| **Parametric internalization** | changed weights | zero retrieval cost, "instinctive" access | catastrophic forgetting, high update cost, and **cannot be precisely removed** |
+
+### Summarization has two shapes and they fail differently
+
+- **Incremental** — fuse each new chunk into the running summary. Supports streaming and
+  avoids reprocessing the whole history. Fails by **semantic drift**: errors compound
+  across iterations, because each summary is built from the last one.
+- **Partitioned** — summarize segments independently, then aggregate. Finer-grained and
+  parallelizable. Fails by **losing cross-partition dependencies**, and by cutting at
+  arbitrary boundaries unless segments are chosen semantically rather than by length.
+
+If you summarize by fixed window size, you have chosen partitioned summarization with the
+worst possible partition rule.
+
+### Distillation splits by what it is distilling
+
+- **Factual** — dialogue turns into stated facts, user intent, environment state. Watch for
+  *goal drift*: separate confirmed constraints from unresolved intents, or the agent starts
+  treating a floated idea as a decision.
+- **Experiential** — strategies from trajectories. **From contrast, not from success.** The
+  survey's own split confirms what §8 of `SKILL.md` already requires: success-only
+  distillation learns the agent's habits, and the systems that work compare successful and
+  failed runs, or reflect against ground truth.
+
+## 2. Choosing among them
+
+The question is not which is best. It is **what the memory will be asked for later**:
+
+| If the later question is… | Form it now with |
+|---|---|
+| "what happened, roughly" | semantic summarization |
+| "what is true about X" | knowledge distillation, factual |
+| "how do I do this kind of task" | knowledge distillation, experiential |
+| "what connects to what" / multi-hop | structured construction |
+| "match this to anything similar" at volume | latent |
+| "behave this way, always, with no lookup" | parametric — and read §2 of `memory-architecture.md` on why this is rarely the answer |
+
+**A schema chosen before this question has been asked is a guess.** The commonest and most
+expensive version of that guess is a knowledge graph built because graphs sound thorough,
+then maintained for multi-hop queries nobody runs.
+
+## 3. Evolution — consolidation
+
+Merging new entries with existing ones so learning is cumulative rather than a growing pile
+of near-duplicates. Three granularities:
+
+- **Local** — a new entry retrieves its top-K nearest and a model decides whether to merge.
+  Cheapest, and the one to build first.
+- **Cluster-level** — align a new cluster with similar existing clusters and fuse. Captures
+  regularities across instances that local merging cannot see.
+- **Global integration** — periodically distil system-level insight from the whole store.
+
+**The cost of consolidation, which is the reason not to run it aggressively:**
+*"it risks information smoothing, where outlier events or unique exceptions are lost during
+the abstraction process."* The exception is often the entry worth keeping — see §5.
+
+## 4. Evolution — updating, and the stability–plasticity dilemma
+
+Updating resolves *conflict*; consolidation performs *abstraction*. They are different
+operations and a system needs both.
+
+**The trajectory the field took, and it is worth copying rather than rediscovering:**
+early systems detected a conflict and **replaced or deleted** the old entry — destructive,
+and it erased historical context and broke temporal continuity. The better pattern is
+**temporal annotation**: mark the superseded fact with a validity window instead of
+deleting it. Soft, time-aware updating keeps both semantic consistency and history.
+
+**Dual-phase updating** is the shape that survives real load: a soft online update for
+responsiveness, then an offline reflective pass that merges similar entries and resolves
+conflicts properly. Eventual consistency, deliberately — because doing full reflective
+consolidation inline puts a model call on the write path of every interaction.
+
+**The dilemma has no general answer:** *"determining when to overwrite existing knowledge
+versus when to treat new information as noise. Incorrect updates can overwrite critical
+information."* What a system can do is make the decision **reversible** — which is the
+argument for annotation over deletion, again.
+
+## 5. Evolution — forgetting
+
+Three policies on three different signals — creation time, access frequency, judged
+importance. They are orthogonal and most systems need more than one.
+
+| Policy | Signal | Watch for |
+|---|---|---|
+| **Time-based** | age | evicting on age alone drops stable facts that were simply written early |
+| **Frequency-based** | reads | **the long-tail trap** — see below |
+| **Importance-driven** | a composite, increasingly a model's judgement of salience | the judge becomes a dependency, and an unaudited judge silently sets policy |
+
+**The long-tail trap, stated because frequency-based eviction is the easy one to reach
+for:** *"heuristic forgetting mechanisms like LRU may eliminate long-tail knowledge, which
+is seldom accessed but essential for correct decision-making."* The entry read twice a year
+is often the incident, the exception, the one customer whose setup differs — precisely the
+entry that prevents an expensive mistake.
+
+**The rule:** where storage is not the binding constraint, **demote rather than delete**.
+Move it out of the default retrieval path, keep it reachable by explicit query. The survey
+reports this is what many systems do in practice: *"when storage cost is not a critical
+constraint, many memory systems avoid directly deleting certain memories."*
+
+Deletion remains a **correctness and privacy** operation — a person asking to be forgotten
+is not a capacity decision, and `memory-architecture.md` §8 covers it.
+
+## 6. What this pack already implements
+
+Stated so this file is read as an extension and not as a replacement:
+
+| Survey concept | Where it already lives here |
+|---|---|
+| Formation, experiential, from contrast | `SKILL.md` §8 · `patterns.md` → Learning Extraction Heuristics |
+| Consolidation, local | `patterns.md` → Fuzzy Deduplication |
+| Updating, conflict resolution | `patterns.md` → Conflict Resolution |
+| Forgetting, time-based | `patterns.md` → Confidence Management |
+| Global integration, cross-scope | `patterns.md` → Cross-Resource Learning Transfer |
+| **Frequency-based forgetting** | **nowhere — and the long-tail trap above is why that is a deliberate omission rather than a gap to close carelessly** |
+| **Temporal annotation instead of deletion** | **nowhere** — Conflict Resolution currently resolves rather than annotates |
+| **Dual-phase updating** | **nowhere** — the pack updates inline |
+
+The last three are named as absent rather than quietly added: each is a real change to a
+mechanism that is in production, and this file's job is to say what the options are, not to
+change `patterns.md` from a survey.