power-loop 3.0.1__tar.gz → 3.1.0__tar.gz

{power_loop-3.0.1 → power_loop-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 3.0.1
+Version: 3.1.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -106,7 +106,7 @@ print((await loop.send("And my second-favorite?", session_id=sid)).final_text)
 pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysql] for those backends
 ```
 
-> **1.0 — stable.** The public API is frozen under SemVer (a breaking change requires a major bump), machine-enforced by a baseline guard in CI. The **core has zero runtime dependencies** (pure stdlib; verified by a CI job that imports it with nothing else installed) — LLM transports *and database drivers* are optional extras. See [Stability](#stability--semver) and the [honest caveats](#honest-scope) — a young, single-maintainer project says so plainly.
+> **Stable since 1.0; now 3.x.** The public API is frozen under SemVer and machine-enforced by a baseline guard in CI — and the two major bumps since prove the discipline rather than undercut it: **2.0** moved storage to a pluggable async backend, **3.0** made context handling two orthogonal axes. Both were real breaking changes, so both got a major bump. The **core has zero runtime dependencies** (pure stdlib; verified by a CI job that imports it with nothing else installed) — LLM transports *and database drivers* are optional extras. Backed by **900+ unit tests**, a **live-LLM** suite, and a **3-backend conformance suite** (SQLite/PostgreSQL/MySQL). See [Stability](#stability--semver) and the [honest caveats](#honest-scope) — a young, single-maintainer project says so plainly.
 
 ---
 
@@ -116,7 +116,7 @@ pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysq
 |---|---|
 | 🚀 **New** — show me the 5-minute version | [Getting Started](docs/en/getting-started.md) |
 | 🛠️ **Learning by building** | [Tutorials](docs/en/tutorials/index.md) — chatbot · tools · human-in-the-loop · multi-agent |
-| 🧩 **Browsing runnable code** | [40 examples](examples/README.md) — `00_hello_world.py` → full chatbot |
+| 🧩 **Browsing runnable code** | [43 examples](examples/README.md) — `00_hello_world.py` → full chatbot |
 | 📚 **Looking something up** | [User Guide](docs/en/user-guide/index.md) · [API reference](docs/en/api/index.md) |
 | 🤔 **Deciding if it fits** | [How it compares](#how-it-compares) · [Honest scope](#honest-scope) |
 
@@ -128,10 +128,11 @@ pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysq
 
 Most "agent frameworks" ask you to build your app *inside* them. power-loop is the opposite: a **library you embed**. You keep your HTTP layer, your auth, your queues, your RAG, your UI, your deploy. It runs the agent loop — and lets you *engineer* it.
 
-- 🪶 **Featherweight & zero-dependency.** No `pydantic`, no LangChain, no graph DSL. A compact, pure-stdlib core (~20k lines) whose public surface is essentially one class — and **zero runtime dependencies**. LLM transports *and* the Postgres/MySQL drivers are pulled in only by the extra you install.
+- 🪶 **Featherweight & zero-dependency.** No `pydantic`, no LangChain, no graph DSL. A compact, pure-stdlib core (~24k lines) whose public surface is essentially one class — and **zero runtime dependencies**. LLM transports *and* the Postgres/MySQL drivers are pulled in only by the extra you install.
 - 🗄️ **Pluggable storage, zero-infra default.** Sessions, timers, sub-agent trees, workflow journals, the shared blackboard — one backend-neutral store written once against a tiny `Database`/`Dialect` port. The default is **one SQLite file** (copy the file, you've copied the state); point a DSN at **PostgreSQL or MySQL** when you want a real multi-writer server — same code, same conformance suite. Tables are auto-created, or **provisioned out-of-band** with a printed DDL script (see [Storage backends](docs/en/user-guide/storage-backends.md)).
 - ♻️ **Stateless, resumable loops.** A `StatefulAgentLoop` carries no authoritative state — all of it lives in the store. So a loop is cheap to create and trivially **restored from a DSN + a session id** (ideal for web handlers, workers, cold starts). It self-caches each session's active window (a rebuildable accelerator that never changes what the model sees) to skip re-reads on hot paths.
 - ⏱️ **Durable by default.** Crash mid-run and `resume()`. Agents schedule their own **durable timers** that survive restarts. Workflows **replay finished steps and re-run only the unfinished tail** after a process death. The store survives version upgrades (a portable, backend-neutral migration-version table) and can be **pruned, VACUUMed, and exported**.
+- 🧠 **Context engineering, not one fixed strategy.** How each finished send is *recorded/rendered* (**representation**: full **verbatim** or a terse per-send **projection**) and how older history is *compacted* once over budget (**fold strategy**: a single **LLM summary**, or an **agentic** pass that also writes durable notes) are two **orthogonal, config-driven axes** — any representation composes with any fold strategy, and both take your own `Representation` / `FoldStrategy` implementation. Folds always keep whole sends (never split a tool-call/result pair); `recall_send` / `recall_compacted` pull the original detail back from the immutable audit log.
 - 🧩 **Composable from one loop to a fleet.** Start with `send()`. Add tools. Spawn sub-agents. Fan out a deterministic **workflow** (`sequence`/`parallel`/`foreach`/`branch`). Run each leaf in its **own process and DB** behind a sandbox. Same primitives all the way up.
 - 🛡️ **Isolation seams where it counts.** Tool-level sandboxing via a `ShellBackend` (drop in gVisor/Docker for `bash`); process-level via a `WorkerLauncher` (wrap a whole sub-agent worker per leaf). power-loop stays sandbox-agnostic; you choose the policy.
 - 🔬 **Built to be observed.** Typed events for every stream chunk, tool call, round, and **individual LLM call** — each `seq`-ordered + monotonic-clock stamped. Pluggable sinks behind extras: durable **JSONL** (with `replay`), **Prometheus/StatsD** metrics, an **OpenTelemetry** span tree. Per-run + per-session token accounting and hard per-run budgets.
@@ -153,14 +154,14 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **Workflow resume** | Journals each step; after a crash, replays completed steps and re-runs only the tail | [Workflows](docs/en/user-guide/workflows.md) |
 | **Process sandboxing** | Each workflow leaf in its own OS process + own DB; wrap each in gVisor/Docker per leaf | [Sandboxing](docs/en/user-guide/sandboxing.md) |
 | **Durable timers** | Agents schedule their own wake-ups; survive restarts; one-shot or recurring | [Timers](docs/en/user-guide/timers.md) |
-| **Context compaction** | Auto-summarize old turns (never splits a tool-call pair); `recall_compacted` to pull originals back | [Compaction](docs/en/user-guide/compaction.md) |
-| **Send-context projection** | Opt-in: feed a per-send plain-text projection of finished sends (derived `pl_project_messages`) instead of verbatim history; `pl_messages` stays immutable; `recall_send` to re-expand | [Projection](docs/en/user-guide/send-context-projection.md) |
+| **Context — representation** | Record/render each finished send **verbatim** or as a terse per-send **projection** (derived `pl_project_messages`); `pl_messages` stays immutable; `recall_send` re-expands | [Projection](docs/en/user-guide/send-context-projection.md) |
+| **Context — fold strategy** | Compact older history once over budget: **LLM summary** or **agentic** (also writes notes); pluggable `FoldStrategy`; never splits a tool pair; `recall_compacted` re-expands | [Compaction](docs/en/user-guide/compaction.md) |
 | **Durability ops** | Portable migration-version table, retention/prune, VACUUM, `export_session`/`import_session`, graceful `aclose()` | [Sessions](docs/en/user-guide/sessions.md) |
 | **Observability** | Typed `seq`-ordered events → durable JSONL + `replay`, Prometheus/StatsD metrics, OpenTelemetry spans | [Observability](docs/en/user-guide/observability.md) |
 | **MCP tools** | Surface a Model Context Protocol server's tools as power-loop tools | [Extending](docs/en/user-guide/extending-tools.md) |
 | **Hooks & events** | Veto/observe at every lifecycle point; strongly-typed event payloads | [Hooks](docs/en/user-guide/hooks.md) · [Events](docs/en/user-guide/events.md) |
 | **Structured output** | `output_schema` → provider `response_format` → parsed & validated | [Structured](docs/en/user-guide/structured-output.md) |
-| **Pluggable memory** | Cross-session recall via a `MemoryProvider` Protocol | [Memory](docs/en/user-guide/memory.md) |
+| **Pluggable memory** | Cross-session recall via a `MemoryProvider` Protocol; a default-on built-in hook injects it ephemerally at the request tail (prefix-cacheable) | [Memory](docs/en/user-guide/memory.md) |
 | **Retry / cancel / budgets** | Provider-aware retry, a unified cancellation token, hard per-run token caps | [Retry & Cancel](docs/en/user-guide/retry-cancel.md) |
 | **Stable error codes** | Every `PowerLoopError` carries a frozen machine-readable `code` — branch on `exc.code` | [API: error codes](docs/en/api/index.md#error-codes) |
 | **Crash recovery** | `heal_pending` / `resume` / `abort_pending` for runs killed mid tool-call | [Pending recovery](docs/en/user-guide/sessions.md#pending-recovery) |
@@ -200,6 +201,28 @@ result = await loop.send(user_text, session_id=session_id)
 
 Under the hood the loop keeps a per-session **active-window cache** — but it caches only the *durable* projection, validated by a monotonic `next_seq` token, so it's a pure accelerator: a cold loop with an empty cache produces byte-for-byte the same prompts (proven by a warm-vs-cold conformance test, including the recall/compaction/prompt-edit edge cases).
 
+### Context engineering — two orthogonal axes you choose (and can implement yourself)
+
+Long conversations outgrow the window. Most libraries give you *one* fixed compaction behavior; power-loop (3.0) splits it into two independent, config-driven axes:
+
+- **Representation** — how each *finished send* is recorded & rendered: `VerbatimRepresentation` (full, byte-identical history) or `ProjectedRepresentation` (a terse per-send plain-text projection). The original detail always stays in the immutable `pl_messages` audit log.
+- **Fold strategy** — how *older* history is compacted once the rendered prefix crosses the budget: `LLMSummaryFold` (one summary call) or `AgenticFold` (a bounded tool loop that also persists durable facts as notes).
+
+```python
+from power_loop import (
+    StatefulAgentLoop, AgentLoopConfig,
+    ProjectedRepresentation, AgenticFold,   # mix & match either axis — or pass your own impl
+)
+
+cfg = AgentLoopConfig(
+    representation=ProjectedRepresentation(max_chars=300),  # terse projection (or VerbatimRepresentation)
+    fold_strategy=AgenticFold(keep_last_sends=4),           # summarize older sends + write notes
+)
+loop = StatefulAgentLoop(llm=llm, dsn="app.db", config=cfg)
+```
+
+Any representation composes with any fold strategy, and each axis is a small `Protocol` you can implement yourself. A fold always keeps **whole sends** (it never splits an atomic tool-call/result pair), and the model can call `recall_send(send_index=N)` / `recall_compacted()` to pull the full original detail back from the audit log. (The two classes above are public but **provisional** — added in 3.0, not yet frozen into `STABLE_API`; `AgentLoopConfig` itself is Stable.)
+
 ### Deterministic multi-agent workflows — that the model can author, and that survive a crash
 
 Sub-agent delegation is *model-driven* ("go do this"). When you want **code-driven, deterministic** orchestration — fan out over a list, branch on a result, run a pipeline — describe it as a `WorkflowSpec` and let the engine interpret it. The only LLM calls are the leaves; `sequence`/`parallel`/`foreach`/`branch` are plain code.
@@ -281,7 +304,7 @@ await register_mcp_tools(registry, client, prefix="fs.")   # MCP tools → power
 
 The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and any client works.
 
-> More: hard token budgets, structured output, crash recovery, memory, the blackboard — see [`examples/`](examples/README.md) (40 runnable programs) and the [docs](docs/en/index.md).
+> More: hard token budgets, structured output, crash recovery, memory, the blackboard — see [`examples/`](examples/README.md) (43 runnable programs) and the [docs](docs/en/index.md).
 
 ---
 
@@ -289,7 +312,7 @@ The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and an
 
 power-loop is a **kernel**, not a platform — that's the whole trade-off.
 
-- **vs. LangChain / LangGraph / LlamaIndex / CrewAI / AutoGen** — those are batteries-included frameworks with large ecosystems (connectors, vector stores, integrations) and heavy dependency trees. power-loop deliberately ships **none of that**: a compact (~20k-line) pure-stdlib core with zero runtime dependencies, and you bring your own tools (or an MCP server). You get durable sessions across SQLite/PG/MySQL, crash-resumable workflows, and real sandbox seams out of the box; you do **not** get a bundled RAG stack or 100 connectors.
+- **vs. LangChain / LangGraph / LlamaIndex / CrewAI / AutoGen** — those are batteries-included frameworks with large ecosystems (connectors, vector stores, integrations) and heavy dependency trees. power-loop deliberately ships **none of that**: a compact (~24k-line) pure-stdlib core with zero runtime dependencies, and you bring your own tools (or an MCP server). You get durable sessions across SQLite/PG/MySQL, crash-resumable workflows, and real sandbox seams out of the box; you do **not** get a bundled RAG stack or 100 connectors.
 - **Choose power-loop** when you want to *embed* an agent in an existing app, keep your dependency surface tiny, pick your own database, and care about durability + isolation + a stable contract.
 - **Choose a framework** when you want batteries included, a big integration catalog, and don't mind the weight.
 
@@ -321,7 +344,7 @@ Python 3.10+. See [Getting Started](docs/en/getting-started.md). Optional extras
 
 ## Stability & SemVer
 
-As of **1.0**, the **STABLE** API (listed in `power_loop.STABLE_API`) is under SemVer: a breaking change requires a major bump (`2.0.0`), enforced by a frozen-baseline test in CI — including the flagship `StatefulAgentLoop` *and the LLM contract needed to construct it*. Error `.code` strings are frozen too.
+Since **1.0**, the **STABLE** API (listed in `power_loop.STABLE_API`) is under SemVer: a breaking change requires a major bump, enforced by a frozen-baseline test in CI — including the flagship `StatefulAgentLoop` *and the LLM contract needed to construct it*. Error `.code` strings are frozen too. The two majors since (2.0 pluggable async storage, 3.0 orthogonal context axes) were exactly that policy in action — breaking changes earned a major bump, each documented in the [Changelog](CHANGELOG.md).
 
 | Tier | Meaning |
 |---|---|

{power_loop-3.0.1 → power_loop-3.1.0}/README.md

@@ -33,7 +33,7 @@ print((await loop.send("And my second-favorite?", session_id=sid)).final_text)
 pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysql] for those backends
 ```
 
-> **1.0 — stable.** The public API is frozen under SemVer (a breaking change requires a major bump), machine-enforced by a baseline guard in CI. The **core has zero runtime dependencies** (pure stdlib; verified by a CI job that imports it with nothing else installed) — LLM transports *and database drivers* are optional extras. See [Stability](#stability--semver) and the [honest caveats](#honest-scope) — a young, single-maintainer project says so plainly.
+> **Stable since 1.0; now 3.x.** The public API is frozen under SemVer and machine-enforced by a baseline guard in CI — and the two major bumps since prove the discipline rather than undercut it: **2.0** moved storage to a pluggable async backend, **3.0** made context handling two orthogonal axes. Both were real breaking changes, so both got a major bump. The **core has zero runtime dependencies** (pure stdlib; verified by a CI job that imports it with nothing else installed) — LLM transports *and database drivers* are optional extras. Backed by **900+ unit tests**, a **live-LLM** suite, and a **3-backend conformance suite** (SQLite/PostgreSQL/MySQL). See [Stability](#stability--semver) and the [honest caveats](#honest-scope) — a young, single-maintainer project says so plainly.
 
 ---
 
@@ -43,7 +43,7 @@ pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysq
 |---|---|
 | 🚀 **New** — show me the 5-minute version | [Getting Started](docs/en/getting-started.md) |
 | 🛠️ **Learning by building** | [Tutorials](docs/en/tutorials/index.md) — chatbot · tools · human-in-the-loop · multi-agent |
-| 🧩 **Browsing runnable code** | [40 examples](examples/README.md) — `00_hello_world.py` → full chatbot |
+| 🧩 **Browsing runnable code** | [43 examples](examples/README.md) — `00_hello_world.py` → full chatbot |
 | 📚 **Looking something up** | [User Guide](docs/en/user-guide/index.md) · [API reference](docs/en/api/index.md) |
 | 🤔 **Deciding if it fits** | [How it compares](#how-it-compares) · [Honest scope](#honest-scope) |
 
@@ -55,10 +55,11 @@ pip install 'power-loop[openai]'      # or [anthropic] · add [postgres] / [mysq
 
 Most "agent frameworks" ask you to build your app *inside* them. power-loop is the opposite: a **library you embed**. You keep your HTTP layer, your auth, your queues, your RAG, your UI, your deploy. It runs the agent loop — and lets you *engineer* it.
 
-- 🪶 **Featherweight & zero-dependency.** No `pydantic`, no LangChain, no graph DSL. A compact, pure-stdlib core (~20k lines) whose public surface is essentially one class — and **zero runtime dependencies**. LLM transports *and* the Postgres/MySQL drivers are pulled in only by the extra you install.
+- 🪶 **Featherweight & zero-dependency.** No `pydantic`, no LangChain, no graph DSL. A compact, pure-stdlib core (~24k lines) whose public surface is essentially one class — and **zero runtime dependencies**. LLM transports *and* the Postgres/MySQL drivers are pulled in only by the extra you install.
 - 🗄️ **Pluggable storage, zero-infra default.** Sessions, timers, sub-agent trees, workflow journals, the shared blackboard — one backend-neutral store written once against a tiny `Database`/`Dialect` port. The default is **one SQLite file** (copy the file, you've copied the state); point a DSN at **PostgreSQL or MySQL** when you want a real multi-writer server — same code, same conformance suite. Tables are auto-created, or **provisioned out-of-band** with a printed DDL script (see [Storage backends](docs/en/user-guide/storage-backends.md)).
 - ♻️ **Stateless, resumable loops.** A `StatefulAgentLoop` carries no authoritative state — all of it lives in the store. So a loop is cheap to create and trivially **restored from a DSN + a session id** (ideal for web handlers, workers, cold starts). It self-caches each session's active window (a rebuildable accelerator that never changes what the model sees) to skip re-reads on hot paths.
 - ⏱️ **Durable by default.** Crash mid-run and `resume()`. Agents schedule their own **durable timers** that survive restarts. Workflows **replay finished steps and re-run only the unfinished tail** after a process death. The store survives version upgrades (a portable, backend-neutral migration-version table) and can be **pruned, VACUUMed, and exported**.
+- 🧠 **Context engineering, not one fixed strategy.** How each finished send is *recorded/rendered* (**representation**: full **verbatim** or a terse per-send **projection**) and how older history is *compacted* once over budget (**fold strategy**: a single **LLM summary**, or an **agentic** pass that also writes durable notes) are two **orthogonal, config-driven axes** — any representation composes with any fold strategy, and both take your own `Representation` / `FoldStrategy` implementation. Folds always keep whole sends (never split a tool-call/result pair); `recall_send` / `recall_compacted` pull the original detail back from the immutable audit log.
 - 🧩 **Composable from one loop to a fleet.** Start with `send()`. Add tools. Spawn sub-agents. Fan out a deterministic **workflow** (`sequence`/`parallel`/`foreach`/`branch`). Run each leaf in its **own process and DB** behind a sandbox. Same primitives all the way up.
 - 🛡️ **Isolation seams where it counts.** Tool-level sandboxing via a `ShellBackend` (drop in gVisor/Docker for `bash`); process-level via a `WorkerLauncher` (wrap a whole sub-agent worker per leaf). power-loop stays sandbox-agnostic; you choose the policy.
 - 🔬 **Built to be observed.** Typed events for every stream chunk, tool call, round, and **individual LLM call** — each `seq`-ordered + monotonic-clock stamped. Pluggable sinks behind extras: durable **JSONL** (with `replay`), **Prometheus/StatsD** metrics, an **OpenTelemetry** span tree. Per-run + per-session token accounting and hard per-run budgets.
@@ -80,14 +81,14 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **Workflow resume** | Journals each step; after a crash, replays completed steps and re-runs only the tail | [Workflows](docs/en/user-guide/workflows.md) |
 | **Process sandboxing** | Each workflow leaf in its own OS process + own DB; wrap each in gVisor/Docker per leaf | [Sandboxing](docs/en/user-guide/sandboxing.md) |
 | **Durable timers** | Agents schedule their own wake-ups; survive restarts; one-shot or recurring | [Timers](docs/en/user-guide/timers.md) |
-| **Context compaction** | Auto-summarize old turns (never splits a tool-call pair); `recall_compacted` to pull originals back | [Compaction](docs/en/user-guide/compaction.md) |
-| **Send-context projection** | Opt-in: feed a per-send plain-text projection of finished sends (derived `pl_project_messages`) instead of verbatim history; `pl_messages` stays immutable; `recall_send` to re-expand | [Projection](docs/en/user-guide/send-context-projection.md) |
+| **Context — representation** | Record/render each finished send **verbatim** or as a terse per-send **projection** (derived `pl_project_messages`); `pl_messages` stays immutable; `recall_send` re-expands | [Projection](docs/en/user-guide/send-context-projection.md) |
+| **Context — fold strategy** | Compact older history once over budget: **LLM summary** or **agentic** (also writes notes); pluggable `FoldStrategy`; never splits a tool pair; `recall_compacted` re-expands | [Compaction](docs/en/user-guide/compaction.md) |
 | **Durability ops** | Portable migration-version table, retention/prune, VACUUM, `export_session`/`import_session`, graceful `aclose()` | [Sessions](docs/en/user-guide/sessions.md) |
 | **Observability** | Typed `seq`-ordered events → durable JSONL + `replay`, Prometheus/StatsD metrics, OpenTelemetry spans | [Observability](docs/en/user-guide/observability.md) |
 | **MCP tools** | Surface a Model Context Protocol server's tools as power-loop tools | [Extending](docs/en/user-guide/extending-tools.md) |
 | **Hooks & events** | Veto/observe at every lifecycle point; strongly-typed event payloads | [Hooks](docs/en/user-guide/hooks.md) · [Events](docs/en/user-guide/events.md) |
 | **Structured output** | `output_schema` → provider `response_format` → parsed & validated | [Structured](docs/en/user-guide/structured-output.md) |
-| **Pluggable memory** | Cross-session recall via a `MemoryProvider` Protocol | [Memory](docs/en/user-guide/memory.md) |
+| **Pluggable memory** | Cross-session recall via a `MemoryProvider` Protocol; a default-on built-in hook injects it ephemerally at the request tail (prefix-cacheable) | [Memory](docs/en/user-guide/memory.md) |
 | **Retry / cancel / budgets** | Provider-aware retry, a unified cancellation token, hard per-run token caps | [Retry & Cancel](docs/en/user-guide/retry-cancel.md) |
 | **Stable error codes** | Every `PowerLoopError` carries a frozen machine-readable `code` — branch on `exc.code` | [API: error codes](docs/en/api/index.md#error-codes) |
 | **Crash recovery** | `heal_pending` / `resume` / `abort_pending` for runs killed mid tool-call | [Pending recovery](docs/en/user-guide/sessions.md#pending-recovery) |
@@ -127,6 +128,28 @@ result = await loop.send(user_text, session_id=session_id)
 
 Under the hood the loop keeps a per-session **active-window cache** — but it caches only the *durable* projection, validated by a monotonic `next_seq` token, so it's a pure accelerator: a cold loop with an empty cache produces byte-for-byte the same prompts (proven by a warm-vs-cold conformance test, including the recall/compaction/prompt-edit edge cases).
 
+### Context engineering — two orthogonal axes you choose (and can implement yourself)
+
+Long conversations outgrow the window. Most libraries give you *one* fixed compaction behavior; power-loop (3.0) splits it into two independent, config-driven axes:
+
+- **Representation** — how each *finished send* is recorded & rendered: `VerbatimRepresentation` (full, byte-identical history) or `ProjectedRepresentation` (a terse per-send plain-text projection). The original detail always stays in the immutable `pl_messages` audit log.
+- **Fold strategy** — how *older* history is compacted once the rendered prefix crosses the budget: `LLMSummaryFold` (one summary call) or `AgenticFold` (a bounded tool loop that also persists durable facts as notes).
+
+```python
+from power_loop import (
+    StatefulAgentLoop, AgentLoopConfig,
+    ProjectedRepresentation, AgenticFold,   # mix & match either axis — or pass your own impl
+)
+
+cfg = AgentLoopConfig(
+    representation=ProjectedRepresentation(max_chars=300),  # terse projection (or VerbatimRepresentation)
+    fold_strategy=AgenticFold(keep_last_sends=4),           # summarize older sends + write notes
+)
+loop = StatefulAgentLoop(llm=llm, dsn="app.db", config=cfg)
+```
+
+Any representation composes with any fold strategy, and each axis is a small `Protocol` you can implement yourself. A fold always keeps **whole sends** (it never splits an atomic tool-call/result pair), and the model can call `recall_send(send_index=N)` / `recall_compacted()` to pull the full original detail back from the audit log. (The two classes above are public but **provisional** — added in 3.0, not yet frozen into `STABLE_API`; `AgentLoopConfig` itself is Stable.)
+
 ### Deterministic multi-agent workflows — that the model can author, and that survive a crash
 
 Sub-agent delegation is *model-driven* ("go do this"). When you want **code-driven, deterministic** orchestration — fan out over a list, branch on a result, run a pipeline — describe it as a `WorkflowSpec` and let the engine interpret it. The only LLM calls are the leaves; `sequence`/`parallel`/`foreach`/`branch` are plain code.
@@ -208,7 +231,7 @@ await register_mcp_tools(registry, client, prefix="fs.")   # MCP tools → power
 
 The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and any client works.
 
-> More: hard token budgets, structured output, crash recovery, memory, the blackboard — see [`examples/`](examples/README.md) (40 runnable programs) and the [docs](docs/en/index.md).
+> More: hard token budgets, structured output, crash recovery, memory, the blackboard — see [`examples/`](examples/README.md) (43 runnable programs) and the [docs](docs/en/index.md).
 
 ---
 
@@ -216,7 +239,7 @@ The seam is a tiny `MCPToolSource` Protocol, so the `mcp` SDK is optional and an
 
 power-loop is a **kernel**, not a platform — that's the whole trade-off.
 
-- **vs. LangChain / LangGraph / LlamaIndex / CrewAI / AutoGen** — those are batteries-included frameworks with large ecosystems (connectors, vector stores, integrations) and heavy dependency trees. power-loop deliberately ships **none of that**: a compact (~20k-line) pure-stdlib core with zero runtime dependencies, and you bring your own tools (or an MCP server). You get durable sessions across SQLite/PG/MySQL, crash-resumable workflows, and real sandbox seams out of the box; you do **not** get a bundled RAG stack or 100 connectors.
+- **vs. LangChain / LangGraph / LlamaIndex / CrewAI / AutoGen** — those are batteries-included frameworks with large ecosystems (connectors, vector stores, integrations) and heavy dependency trees. power-loop deliberately ships **none of that**: a compact (~24k-line) pure-stdlib core with zero runtime dependencies, and you bring your own tools (or an MCP server). You get durable sessions across SQLite/PG/MySQL, crash-resumable workflows, and real sandbox seams out of the box; you do **not** get a bundled RAG stack or 100 connectors.
 - **Choose power-loop** when you want to *embed* an agent in an existing app, keep your dependency surface tiny, pick your own database, and care about durability + isolation + a stable contract.
 - **Choose a framework** when you want batteries included, a big integration catalog, and don't mind the weight.
 
@@ -248,7 +271,7 @@ Python 3.10+. See [Getting Started](docs/en/getting-started.md). Optional extras
 
 ## Stability & SemVer
 
-As of **1.0**, the **STABLE** API (listed in `power_loop.STABLE_API`) is under SemVer: a breaking change requires a major bump (`2.0.0`), enforced by a frozen-baseline test in CI — including the flagship `StatefulAgentLoop` *and the LLM contract needed to construct it*. Error `.code` strings are frozen too.
+Since **1.0**, the **STABLE** API (listed in `power_loop.STABLE_API`) is under SemVer: a breaking change requires a major bump, enforced by a frozen-baseline test in CI — including the flagship `StatefulAgentLoop` *and the LLM contract needed to construct it*. Error `.code` strings are frozen too. The two majors since (2.0 pluggable async storage, 3.0 orthogonal context axes) were exactly that policy in action — breaking changes earned a major bump, each documented in the [Changelog](CHANGELOG.md).
 
 | Tier | Meaning |
 |---|---|

{power_loop-3.0.1 → power_loop-3.1.0}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "3.0.1"
+__version__ = "3.1.0"
 
 # Public LLM contract (SDK-free) re-exported so callers (e.g. writing llm.* hooks or
 # a custom LLMService) don't reach into the internal vendored transport package (H3.4).
@@ -154,9 +154,15 @@ from power_loop.runtime.fold import (
     NoteOp,
 )
 from power_loop.runtime.human_input import HumanInputRequired, request_user_input
-from power_loop.runtime.memory import MemoryProvider, MemorySnapshot, tag_as_memory
+from power_loop.runtime.memory import (
+    MemoryProvider,
+    MemoryRecallHook,
+    MemorySnapshot,
+    tag_as_memory,
+)
 from power_loop.runtime.notes import (
     DEFAULT_NOTES_POLICY,
+    NoteMemory,
     NotesFullError,
     NotesPolicy,
     SQLiteNoteMemory,
@@ -361,10 +367,12 @@ __all__ = [
 	"LlmDegradedPayload",
 	"LoopCancelledPayload",
 	"MemoryProvider",
+	"MemoryRecallHook",
 	"MemorySnapshot",
 	"tag_as_memory",
 	"NotesPolicy",
 	"NotesFullError",
+	"NoteMemory",
 	"SQLiteNoteMemory",
 	"DEFAULT_NOTES_POLICY",
 	"render_notes",

{power_loop-3.0.1 → power_loop-3.1.0}/power_loop/agent/sink.py

@@ -32,7 +32,6 @@ class MessageSink(Protocol):
 
     async def on_round_started(self, round_index: int) -> None: ...
     async def on_message_appended(self, message: LoopMessage, *, round_index: int | None) -> None: ...
-    def on_messages_inserted(self, *, index: int, count: int) -> None: ...  # pure (no I/O) → sync
     async def on_assistant_tool_calls(
         self, *, assistant_seq: int, tool_calls: list[dict[str, Any]], round_index: int
     ) -> None: ...
@@ -57,7 +56,6 @@ class NullSink:
 
     async def on_round_started(self, round_index: int) -> None: ...
     async def on_message_appended(self, message: LoopMessage, *, round_index: int | None) -> None: ...
-    def on_messages_inserted(self, *, index: int, count: int) -> None: ...
     async def on_assistant_tool_calls(
         self, *, assistant_seq: int, tool_calls: list[dict[str, Any]], round_index: int
     ) -> None: ...
@@ -129,16 +127,12 @@ class SQLiteSink:
         self._history_seqs = list(seqs)
         self._history_ord = list(ords) if ords is not None else list(seqs)
 
-    def on_messages_inserted(self, *, index: int, count: int) -> None:
-        """Record that ``count`` in-memory-only messages were spliced into
-        ``pipeline.history`` at ``index`` without being persisted (recalled
-        ``memory_*``). Insert matching ``None`` placeholders so ``_history_seqs``
-        stays index-aligned with ``history`` and later folds map to the right rows."""
-        if count <= 0:
-            return
-        idx = max(0, min(index, len(self._history_seqs)))
-        self._history_seqs[idx:idx] = [None] * count
-        self._history_ord[idx:idx] = [None] * count
+    # NOTE: on_messages_inserted was removed when memory recall moved to the
+    # ephemeral tail-injection LLM_BEFORE hook (it never enters self.history, so
+    # there is no in-memory-only row to align). The _history_seqs/_history_ord
+    # maps stay `list[int | None]` and on_compaction keeps its None-guards: those
+    # remain load-bearing for projection mode (seeds None prefixes) and for
+    # corrupt-history repair (align_tool_calls synthesizes placeholders).
 
     # ── messages ───────────────────────────────────────────────
 

{power_loop-3.0.1 → power_loop-3.1.0}/power_loop/agent/stateful_loop.py

@@ -31,10 +31,7 @@ from power_loop._vendor.llm_client.interface import LLMService
 from power_loop.agent.follow_up import FollowUpQueued, merge_follow_up_inputs
 from power_loop.agent.sink import SQLiteSink
 from power_loop.agent.system_prompt import (
-    DEFAULT_AGENT_SYSTEM_PROMPT,
-    SystemPromptContext,
-    format_tool_catalog,
-    section_skills,
+    resolve_runtime_system_prompt,
 )
 from power_loop.agent.types import AgentLoopConfig, AgentLoopResult, LoopMessage
 from power_loop.contracts.errors import SessionNotFoundError, SessionPendingError
@@ -51,7 +48,6 @@ from power_loop.core.runner import AgentRunner
 from power_loop.runtime.budget import estimate_tokens
 from power_loop.runtime.cancellation import CancellationLike
 from power_loop.runtime.history_sanitize import align_tool_calls
-from power_loop.runtime.skills import SkillLoader
 from power_loop.runtime.store.schema import SchemaPolicy
 from power_loop.runtime.store.store import (
     DEFAULT_DB_PATH,
@@ -210,7 +206,13 @@ class StatefulAgentLoop:
         self._orphaned_close_task: asyncio.Future[None] | None = None
         self.config = config if config is not None else AgentLoopConfig()
         self.tool_registry = tool_registry
-        self._runner = AgentRunner(event_bus=event_bus, hooks=hooks)
+        # Own a FRESH AgentHooks when the caller supplies none — NOT the shared
+        # module-level DEFAULT_HOOKS singleton — so per-loop built-in hooks (e.g.
+        # the memory recall hook) don't stack across loops or leak config.
+        self._runner = AgentRunner(
+            event_bus=event_bus, hooks=hooks if hooks is not None else AgentHooks()
+        )
+        self._register_builtin_hooks()
         self._locks: dict[str, asyncio.Lock] = {}
         self._follow_up_queues: dict[str, list[str | LoopMessage]] = {}
         self._follow_up_queue_locks: dict[str, asyncio.Lock] = {}
@@ -222,6 +224,33 @@ class StatefulAgentLoop:
         self._cache_misses = 0
         self._cache_evictions = 0
 
+    def _register_builtin_hooks(self) -> None:
+        """Register power-loop's default functional hooks on this loop's own
+        AgentHooks. They carry a ``builtin.*`` name so a host can override them
+        (``hooks.replace(..., name=...)``) or disable them (``hooks.remove(...)``).
+        """
+        cfg = self.config
+        if cfg.memory is not None and getattr(cfg, "builtin_memory_hook", True):
+            from power_loop.contracts.hooks import HookPoint
+            from power_loop.runtime.memory import MemoryRecallHook
+
+            hook = MemoryRecallHook(
+                cfg.memory,
+                budget_tokens=int(cfg.memory_budget_tokens or 0),
+                position=getattr(cfg, "memory_position", "tail"),
+                hooks=self._runner.hooks,
+                event_bus=self._runner.event_bus,
+            )
+            # order=100 → runs AFTER host LLM_BEFORE hooks (default order 0) so
+            # memory lands at the true request tail. Skip if the host already
+            # registered one under this name (their override wins); a host can
+            # also override/disable post-construction via loop.hooks.replace /
+            # .remove(MemoryRecallHook.NAME).
+            if not self._runner.hooks.has(MemoryRecallHook.NAME):
+                self._runner.hooks.register(
+                    HookPoint.LLM_BEFORE, hook, order=100, name=MemoryRecallHook.NAME,
+                )
+
     async def ensure_store(self) -> SessionStore:
         """Public accessor: return this loop's store, opening an owned one on first use.
 
@@ -906,9 +935,14 @@ class StatefulAgentLoop:
         Returns
         -------
         str
-            The fully resolved prompt string — exactly what the LLM
-            will see as the system message on the next :meth:`send`
-            call.
+            The fully resolved prompt for a :meth:`send` with **no per-call
+            overrides** — base (session/config) + auto-injected tool catalog
+            (full registry) + skill section, via the same
+            ``resolve_runtime_system_prompt`` helper the live pipeline uses.
+
+            A per-call ``send(system_prompt=...)`` or ``send(tools=[...])`` is
+            applied at send time and is NOT reflected here (this previews the
+            no-override case; pass nothing at ``send`` for a byte-identical match).
         """
         # Session-level prompt wins over config-level prompt.
         base: str | None = None
@@ -917,36 +951,18 @@ class StatefulAgentLoop:
             row = await store.get_session(session_id)
             if row is not None:
                 base = row.system_prompt
-
         if base is None or not base.strip():
-            base = self.config.system_prompt or DEFAULT_AGENT_SYSTEM_PROMPT
-
-        base = base.strip()
-
-        if self.config.inject_tool_descriptions and self.tool_registry is not None:
-            catalog = format_tool_catalog(
-                self.tool_registry,
-                header=self.config.tool_catalog_header,
-            )
-            if catalog:
-                base = f"{base}\n\n{catalog}"
-
-        skills = None
-        if self.config.skills_dir:
-            try:
-                loader = SkillLoader(self.config.skills_dir)
-                skills = section_skills(
-                    SystemPromptContext(
-                        skills_dir=str(loader.skills_dir),
-                        skill_descriptions=loader.get_descriptions(),
-                    )
-                )
-            except Exception:
-                skills = None
-        if skills:
-            base = f"{base}\n\n{skills}"
-
-        return base
+            base = self.config.system_prompt
+
+        # Shared assembly — the SAME helper AgentPipeline.__init__ uses — so this
+        # preview is byte-identical to what the LLM actually receives.
+        return resolve_runtime_system_prompt(
+            base,
+            inject_tool_descriptions=self.config.inject_tool_descriptions,
+            tool_catalog_header=self.config.tool_catalog_header,
+            tool_registry=self.tool_registry,
+            skills_dir=self.config.skills_dir,
+        )
 
     # ── internals ─────────────────────────────────────────────────────────
 
@@ -1645,7 +1661,9 @@ class StatefulAgentLoop:
             if len(live_sends) <= keep:
                 return None, ()  # nothing foldable beyond the keep-recent floor
             trigger_ratio = float(getattr(fold_strategy, "trigger_ratio", 0.75) or 0.75)
-            threshold = int((self.config.max_tokens or 8000) * trigger_ratio)
+            # Reserve headroom for the ephemeral tail-injected memory block (not
+            # part of the projected snapshot, so invisible here) — fold earlier.
+            threshold = int((self.config.effective_context_budget() or 8000) * trigger_ratio)
             rendered_prefix = projector.render(([prior] if prior is not None else []) + snapshot)
             if estimate_tokens(rendered_prefix) < threshold:
                 return None, ()  # below threshold — small per-send projections just accumulate

{power_loop-3.0.1 → power_loop-3.1.0}/power_loop/agent/system_prompt.py

@@ -417,6 +417,56 @@ DEFAULT_EXPLORE_SUBAGENT_SYSTEM_PROMPT = (
 ).build(SystemPromptContext())
 
 
+def build_skill_section(skills_dir: str | None) -> str:
+    """Render the auto-injected skill-catalog section for ``skills_dir``.
+
+    Returns ``""`` when no skills_dir is set or loading fails. Lazy-imports
+    SkillLoader to avoid a core↔runtime import cycle.
+    """
+    if not skills_dir:
+        return ""
+    try:
+        from power_loop.runtime.skills import SkillLoader
+
+        loader = SkillLoader(skills_dir)
+        section = section_skills(
+            SystemPromptContext(
+                skills_dir=str(loader.skills_dir),
+                skill_descriptions=loader.get_descriptions(),
+            )
+        )
+        return section or ""
+    except Exception:
+        return ""
+
+
+def resolve_runtime_system_prompt(
+    base: str | None,
+    *,
+    inject_tool_descriptions: bool,
+    tool_catalog_header: str,
+    tool_registry: Any,
+    skills_dir: str | None,
+) -> str:
+    """Single source of truth for runtime system-prompt assembly:
+    ``base → tool catalog → skill section`` (each joined by ``"\\n\\n"``).
+
+    Shared by :meth:`AgentPipeline.__init__` (the live prompt) and
+    :meth:`StatefulAgentLoop.resolve_system_prompt` (the preview), so the two
+    can never drift. Callers resolve ``base`` themselves (config vs session
+    override) and pass it in; everything after is computed here once.
+    """
+    out = (base or DEFAULT_AGENT_SYSTEM_PROMPT).strip()
+    if inject_tool_descriptions and tool_registry is not None:
+        catalog = format_tool_catalog(tool_registry, header=tool_catalog_header)
+        if catalog:
+            out = f"{out}\n\n{catalog}"
+    skill = build_skill_section(skills_dir)
+    if skill:
+        out = f"{out}\n\n{skill}"
+    return out
+
+
 def build_agent_system_prompt(
     ctx: SystemPromptContext,
     extra: str | None = None,

{power_loop-3.0.1 → power_loop-3.1.0}/power_loop/agent/types.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import warnings
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Literal
@@ -111,6 +112,37 @@ class AgentLoopConfig:
     retry_policy: LLMRetryPolicy | None = None
     memory: MemoryProvider | None = None
     memory_budget_tokens: int = 1500
+    #: Where the built-in MemoryRecallHook injects recalled memory into the
+    #: per-call request: "tail" (default — after history, keeps the prior-history
+    #: prefix byte-stable and prefix-cacheable) or "front" (after leading system
+    #: messages — legacy position; breaks prefix caching when memory changes).
+    memory_position: str = "tail"
+    #: Auto-register the built-in MemoryRecallHook when ``memory`` is set. Turn
+    #: off to inject memory yourself via an LLM_BEFORE hook.
+    builtin_memory_hook: bool = True
+
+    # ── Microcompact (large tool-output spill-to-disk) ──
+    #
+    # A cheap, no-LLM per-round mechanism that replaces OLD oversized tool
+    # outputs (older than the hot tail) with a short on-disk pointer, to save
+    # context tokens — orthogonal to the LLM-summary fold/compactor. Verbatim
+    # mode only (projection renders finished sends from the projection store).
+    #
+    # DEFAULT OFF as of 3.1.x: it only helps when those old outputs are never
+    # needed again; otherwise the pointer just trades for a re-read. Projection
+    # mode + fold + provider prefix-caching already cover context budget. Turn it
+    # on for long verbatim sessions that read many large files and rarely revisit
+    # the old ones. The thresholds default from the legacy CONTEXT_MICRO_* env
+    # vars for back-compat; the config fields take precedence.
+    microcompact_enabled: bool = False
+    microcompact_size_limit: int = field(
+        default_factory=lambda: int(os.getenv("CONTEXT_MICRO_SIZE_LIMIT", "1000"))
+    )
+    microcompact_hot_tail: int = field(
+        default_factory=lambda: int(os.getenv("CONTEXT_MICRO_HOT_TAIL", "10"))
+    )
+    #: Where spilled outputs are written. None → the runtime home's ``.cache``.
+    microcompact_spill_dir: str | None = None
     # Bounds for the note_add/note_update/note_delete tools (agent-authored
     # notes). None → DEFAULT_NOTES_POLICY. See power_loop.runtime.notes.
     notes_policy: NotesPolicy | None = None
@@ -132,6 +164,24 @@ class AgentLoopConfig:
     inject_tool_descriptions: bool = True
     tool_catalog_header: str = "# Available Tools"
 
+    def effective_context_budget(self) -> int:
+        """Fold/compaction budget after reserving headroom for the ephemeral
+        memory block.
+
+        Memory is injected at the per-call tail by the built-in hook and is NOT
+        counted by the fold trigger (it isn't in ``self.history``). To keep
+        ``history + memory`` within the model window, the fold threshold targets
+        ``max_tokens − memory_budget_tokens`` so folding fires early enough.
+        ``0``/``None`` max_tokens means "no explicit budget" → returned
+        unchanged.
+        """
+        mt = int(self.max_tokens or 0)
+        if mt <= 0:
+            return mt
+        if self.memory is not None and self.builtin_memory_hook:
+            return max(1, mt - int(self.memory_budget_tokens or 0))
+        return mt
+
     def __post_init__(self) -> None:
         self._map_legacy_axes()
         self._validate_context_config()

{power_loop-3.0.1 → power_loop-3.1.0}/power_loop/contracts/hook_contexts.py

@@ -122,7 +122,9 @@ class LlmBeforeCtx(BaseHookCtx):
     """Context for :pyattr:`HookPoint.LLM_BEFORE`.
 
     Directives: SHORT_CIRCUIT (set ``output`` to an ``LLMResponse``), BREAK.
-    Handler may modify any input field.
+    Handler may modify any input field. ``messages`` is the fresh per-call list
+    actually sent to the LLM — mutating it (e.g. appending an ephemeral memory
+    block) never touches the loop's persisted history.
     """
 
     messages: list[LoopMessage] = field(default_factory=list)
@@ -130,6 +132,7 @@ class LlmBeforeCtx(BaseHookCtx):
     tools: list[dict[str, Any]] | None = None
     max_tokens: int = 8000
     temperature: float = 0.0
+    session_id: str | None = None
     # Handler output (for SHORT_CIRCUIT)
     output: LLMResponse | None = None