phronomy 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 633f62428045fed9447fd95414687cf8f2d0df11163afd767a73cc1c9b0ea97e
-  data.tar.gz: 68d352c78047e7b87dade2f8659cf44d4ecd16acf506090329d3e276f8a35f0c
+  metadata.gz: d3af942022237dc3396d6a658f4f1b9be12f03eb0f718ebea81525822f756308
+  data.tar.gz: c046a9670fb3e1e55640f5072ac6c04399edbdfdfc4b2238caefde135fc1a2e5
 SHA512:
-  metadata.gz: 67cd757c8efacd34360a3b876bae0ebbac0e37080f77472a9b69eaf774f14b5f2c070288d4e5d66bbfcc31a6be60353ca043e4f95ee6b1a14da09e8fe5792b00
-  data.tar.gz: '0382e7bbf708605dea900725e7ab4c093baf653ef0e88c11ba79c6ab227b1584624aa73b9b16cacd8644d4d1aafe0ffade1b6b1d6361a1f33d7395e730b4e1df'
+  metadata.gz: f52c37ff47e703de492742a2753870c4e3b4ee63ef58ab0e875afcef1488bef95f6c2f0b96e19181d1fe0f7ec28b15a9f4581f18ce0685eff28ca773eabc3aa1
+  data.tar.gz: 9cdd430036ff931dedc3548005d448f1173bfe135d7eaed8b737f01bf44e23d3467c9ef96a6a0d64d8c6005d1f48b3d57f71e39bb5c9df109fd6230ae784c64a

data/.mutant.yml

@@ -1,22 +1,21 @@
 ---
-# Mutant configuration for Phronomy (opensource project)
-# See: https://github.com/mbj/mutant
-
 usage: opensource
-
 integration: rspec
-
 includes:
   - lib
-
 requires:
   - phronomy
-
 matcher:
   subjects:
     - Phronomy::WorkflowContext
     - Phronomy::WorkflowRunner
     - Phronomy::Tool::Base
-    - Phronomy::Context::TokenBudget
-    - Phronomy::Context::TokenEstimator
+    - Phronomy::LlmContextWindow::TokenBudget
+    - Phronomy::Agent::ContextAssembler
+    - Phronomy::Agent::ContextPolicies::Default
+    - Phronomy::Agent::ContextParts::UnitBuilders::DependencyAwareUnitBuilder
+    - Phronomy::Agent::ContextParts::Requirements::RequiredContextResolver
+    - Phronomy::Agent::ContextParts::Selectors::RecentFirstSelector
+    - Phronomy::Agent::ContextParts::Budget::TokenBudgetPacker
+    - Phronomy::Agent::ContextPlanValidator
     - Phronomy::VectorStore::InMemory

data/CHANGELOG.md

@@ -9,6 +9,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Agent Context / Knowledge cleanup
+
+#### Added
+
+- Journal-backed persistent Agent Knowledge via creation-time `knowledge:` and
+  post-creation `Agent#add_knowledge`.
+- `Agent#clear_knowledge!` for logical Knowledge invalidation without deleting
+  append-only Journal history.
+- ADR-013, defining persistent Knowledge as optional Context candidates selected
+  through the Manifest-first Context Policy pipeline.
+
+#### Changed
+
+- Persistent Knowledge and `before_llm_input` segment candidates now participate
+  in Context Policy and token-budget selection instead of being injected as
+  mandatory system context.
+- `clear_transcript!`, `clear_knowledge!`, and `reset_context!` now have distinct
+  transcript/Knowledge lifecycle semantics.
+- Active Context tests, integration fixtures, benchmarks, mutation subjects,
+  design documents, and API snapshots now describe the canonical
+  Journal -> ContextCandidate -> Context Policy -> Manifest architecture.
+
+#### Removed
+
+- `Phronomy::KnowledgeSource`, `Knowledge::Base`, `StaticKnowledge`, and
+  `EntityKnowledge`.
+- `static_knowledge*`, `add_knowledge_source`, `instance_knowledge_chunks`,
+  `Knowledge#static?`, `StaticKnowledge#source`, and the class-level static
+  Knowledge cache/fetch abstraction.
+- `Agent#clear_memory!` and `AgentRoot#memory_generation`.
+- Remaining no-op ContextVersionCache tests, fake legacy-import Context tests,
+  obsolete Memory/context integration helpers, legacy `:llm_message` benchmark
+  categories, and stale Agent `messages:` test-double signatures.
+
+### Phase 3 cleanup
+
+#### Changed
+
+- Active documentation, compatibility snapshots, benchmarks, integration fixtures,
+  and mutation targets now describe the Manifest-first Context architecture.
+- The Context benchmark now measures `Agent::ContextAssembler` and
+  `ContextPolicies::Default` instead of the removed legacy Assembler.
+- ADR-011 is marked Superseded by ADR-012; its historical analysis is retained.
+
+#### Removed
+
+- Remaining active compatibility references to `context_overhead`,
+  `LlmContextWindow::Assembler`, `ContextVersionCache`, Tool
+  `on_error :return_empty`, `force_kill:`, `runtime_backend :cooperative`,
+  the `Runtime.instance=` setter, tools-splat registration, and wall-clock
+  `CancellationToken.new(deadline:)`.
+- Obsolete legacy Assembler / ContextVersionCache executable specs.
+
+
 ---
 
 ## [0.16.0] - 2026-08-08

data/CONTRIBUTING.md

@@ -58,15 +58,20 @@ When adding, removing, or renaming a public method or class:
 
 Key design decisions are documented as ADRs in
 [docs/decisions/](docs/decisions/). Read these before making significant changes
-to the threading model, caching strategy, or public API shape.
+to the threading model, persistence/context authority, or public API shape.
+
+For Agent Context work, ADR-012 and ADR-013 define the current Journal,
+Manifest, Context Policy and persistent Knowledge model.
 
 ---
 
 ## Mutation Testing
 
-Phronomy uses [mutant](https://github.com/mbj/mutant) to verify that each test
-actually detects real code changes. Mutation tests are **not** part of the
-required CI gate (they are slow), but run nightly via `.github/workflows/nightly-mutation.yml`.
+Phronomy uses [mutant](https://github.com/mbj/mutant) to verify that tests detect
+real code changes. Mutation tests are not part of the required CI gate. The
+repository contains `.github/workflows/nightly-mutation.yml` for mutation-run
+automation; whether that workflow is enabled is an operational choice and is
+not a normal pull-request requirement.
 
 ### Run mutation tests locally
 
@@ -78,18 +83,25 @@ bash scripts/run_mutation.sh
 bash scripts/run_mutation.sh "Phronomy::WorkflowContext"
 ```
 
-### Coverage targets
-
-| Subject | Baseline | Target |
-|---|---|---|
-| `Phronomy::WorkflowContext` | 84.85% | ≥ 80% |
-| `Phronomy::WorkflowRunner` | — | ≥ 80% |
-| `Phronomy::Tool::Base` | 55.74% | ≥ 80% |
-| `Phronomy::Context::TokenBudget` | — | ≥ 80% |
-| `Phronomy::VectorStore::InMemory` | — | ≥ 80% |
-
-When you add or modify tests for a covered subject, run mutation tests to confirm
-the score does not regress.
+### Covered subjects
+
+The authoritative subject list is `.mutant.yml`. It currently includes:
+
+- `Phronomy::WorkflowContext`
+- `Phronomy::WorkflowRunner`
+- `Phronomy::Tool::Base`
+- `Phronomy::LlmContextWindow::TokenBudget`
+- `Phronomy::Agent::ContextAssembler`
+- `Phronomy::Agent::ContextPolicies::Default`
+- `Phronomy::Agent::ContextParts::UnitBuilders::DependencyAwareUnitBuilder`
+- `Phronomy::Agent::ContextParts::Requirements::RequiredContextResolver`
+- `Phronomy::Agent::ContextParts::Selectors::RecentFirstSelector`
+- `Phronomy::Agent::ContextParts::Budget::TokenBudgetPacker`
+- `Phronomy::Agent::ContextPlanValidator`
+- `Phronomy::VectorStore::InMemory`
+
+When you add or modify tests for a covered subject, run mutation tests locally
+when practical and investigate meaningful score regressions.
 
 ---
 

data/README.md

@@ -42,7 +42,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 
 | Feature | Stability |
 |---|---|
-| **Knowledge** — Static context injection with pluggable loaders, splitters, and vector stores; `static_knowledge_refresh!` for runtime cache invalidation | Beta |
+| **Knowledge** — Journal-backed persistent Agent context registered with `knowledge:` / `add_knowledge`; selected per LLM call by Context Policy; `clear_knowledge!` logically resets retained Knowledge without deleting Journal history | Beta |
 | **`VectorStore#size`** — Returns document count for all three backends (InMemory, RedisSearch, Pgvector) | Beta |
 | **`VectorStore::AsyncBackend` mixin** — Pluggable async interface for `VectorStore`; default pool-backed implementations for `search_async`, `add_async`, `remove_async`, `clear_async`; backends with native async drivers override individual methods to bypass `BlockingAdapterPool` entirely; all existing backends remain unchanged | Beta |
 | **MCP Tool** — `Phronomy::Tools::Mcp`: Model Context Protocol server integration via the official `mcp` gem; `Phronomy::Tools::Agent`: wraps an agent class as a callable tool via `from_agent` | Beta |
@@ -57,8 +57,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | **`stream_callback_error_policy`** — Backward-compatible setting shared by `invoke_async` and `stream_async` terminal `on_event:` callbacks: `:report` (default) preserves the Agent result, while `:fail_task` fails the returned Task with `Phronomy::StreamCallbackError`; Agent execution errors are never replaced by callback errors | Beta |
 | **`invoke_async` / `call_async`** — `Agent::Base#invoke_async` and `Workflow#invoke_async` return a `Task`; `Agent::Context::Capability::Base#call_async` similarly; compatible with EventLoop and standalone contexts | Stable |
 | **`Task#map`** — transforms a Task's completed value and propagates failure/cancellation. `Task#map` remains available for application-level Task composition, but Workflow entry and transition actions must not return a Task | Stable |
-| **CancellationToken** — Cooperative cancellation via `cancel!`/`cancelled?`/`raise_if_cancelled!`; `timeout_after(seconds)` for monotonic-clock deadlines; optional `deadline:` (wall-clock) for backward compatibility; passed as `config: { cancellation_token: token }` to agents and `dispatch_parallel`; injected into `tool.execute` when the method declares a `cancellation_token:` keyword; bridged to `MCP::Cancellation` in `Phronomy::Tools::Mcp#execute` | Experimental |
-| **`dispatch_parallel` / `fan_out` `force_kill:` option** — `force_kill: false` (default) leaves timed-out workers running and raises `TimeoutError` immediately; `force_kill: true` restores the old `Thread#kill` behaviour with a `logger.warn` | Beta |
+| **CancellationToken** — Cooperative cancellation via `cancel!`/`cancelled?`/`raise_if_cancelled!`; `timeout_after(seconds)` for monotonic-clock deadlines; passed as `config: { cancellation_token: token }` to agents and `dispatch_parallel`; injected into `tool.execute` when the method declares a `cancellation_token:` keyword; bridged to `MCP::Cancellation` in `Phronomy::Tools::Mcp#execute` | Experimental |
 | **`execution_mode` DSL on `Agent::Context::Capability::Base`** — Declares how a tool's `execute` should be dispatched: `:cooperative` (same scheduler thread), `:blocking_io` (default; offloaded to `BlockingAdapterPool`), `:cpu_bound`, `:external_process`; Tool-specific timeout/retry belongs to the Tool implementation or its client | Experimental |
 | **`blocking_io_pool_size` / `blocking_io_queue_size`** — Configure the default `BlockingAdapterPool` via `Phronomy.configure { \|c\| c.blocking_io_pool_size = 20; c.blocking_io_queue_size = 200 }`; all LLM calls, MCP tool calls, and other blocking I/O share this pool; defaults: `pool_size: 10`, `queue_size: 100` | Beta |
 | **`invocation_context:` keyword on `Agent#invoke` / `Workflow#invoke`** — Pass a `Phronomy::InvocationContext` directly; `thread_id`, `cancellation_token`, and `deadline`-based timeout are derived from it; `task_id` / `parent_task_id` appear in trace spans automatically; `config:` keys remain supported as backward-compat aliases | Beta |
@@ -99,7 +98,7 @@ The APIs listed below are intended for advanced use cases, framework internals,
 |---|---|
 | **`Phronomy::Diagnostics`** — Snapshot of scheduler internals for debug/monitoring; `SchedulerReentrancyError` raised on invalid re-entrant scheduler use; `Runtime.in_scheduler_context?` returns `true` when called from inside a scheduler task | Experimental |
 | **`Phronomy::Testing::FakeClock` / `FakeScheduler` / `SchedulerHelpers`** — Test helpers for deterministic concurrency specs: `FakeClock#advance(seconds)` controls time; `FakeScheduler` runs tasks synchronously and records `event_log`; `FakeScheduler#assert_order` / `#assert_cancelled` for ordering assertions; `FakeClock#advance_to_next_timer` fires the next pending callback; `Testing::SchedulerHelpers#with_fake_scheduler` replaces the global Runtime for the duration of a block | Beta |
-| **`Configuration#runtime_backend`** — `:thread` (default, one OS thread per task), `:immediate` (tests — tasks run synchronously, no extra threads), `:fiber` (**EXPERIMENTAL** — experimental validation backend only: runs tasks as Ruby Fibers on a cooperative scheduler to verify that framework components are truly non-blocking; **not for production use** and not a planned production replacement for `:thread`; no preemptive scheduling will be added). `:cooperative` is a **deprecated alias** for `:immediate` — do not use in new code | Beta |
+| **`Configuration#runtime_backend`** — `:thread` (default, one OS thread per task), `:immediate` (tests — tasks run synchronously, no extra threads), `:fiber` (**EXPERIMENTAL** — validation backend only: runs tasks as Ruby Fibers on a cooperative scheduler to verify that framework components are truly non-blocking; **not for production use** and not a planned production replacement for `:thread`; no preemptive scheduling will be added) | Beta |
 | **`Configuration#strict_runtime_guards`** — When `true`, calling `Agent#invoke` from inside a scheduler task raises `SchedulerReentrancyError`; when `false` (default) a warning is logged instead | Beta |
 
 ## Installation
@@ -150,6 +149,28 @@ See the [RubyLLM documentation](https://rubyllm.com) for all supported providers
 | `InvocationContext#provider_limits` | Configure the provider client directly |
 | `stream_queue_max_size` | No replacement; the shared EventLoop queue is unbounded by design. Monitor `Metrics.snapshot[:event_loop_queue_depth]` instead |
 
+### 0.16 cleanup migration
+
+The following compatibility-only APIs have been removed from the active contract:
+
+| Removed API | Current contract |
+|---|---|
+| `context_overhead` | Manifest-first assembly budgets actual mandatory + selected content |
+| Tool `on_error :return_empty` | Use `:raise` or `:suppress` |
+| `dispatch_parallel(..., force_kill:)` / `fan_out(..., force_kill:)` | Cooperative cancellation; no force-kill switch |
+| `runtime_backend = :cooperative` | Use `:thread`, `:immediate`, or experimental `:fiber` explicitly |
+| `Runtime.instance = ...` | Runtime replacement is test/internal infrastructure, not a public setter |
+| `TaskGroup.new(runtime: nil)` | Runtime is required |
+| `tools ToolA, ToolB` | Use `tools(ToolA => nil, ToolB => nil)` |
+| `CancellationToken.new(deadline: Time...)` | Use `CancellationToken.timeout_after(seconds)` for token deadlines |
+| `StaticKnowledge` / `EntityKnowledge` / `Knowledge::Base` / `Phronomy::KnowledgeSource` | Register plain persistent Knowledge with `knowledge:` or `add_knowledge` |
+| `static_knowledge*` class APIs | Persistent Knowledge belongs to Agent instances and is Journal-backed |
+| `clear_memory!` | Use `clear_knowledge!`; conversation history is controlled independently with `clear_transcript!` |
+
+The legacy `build_context` / `LlmContextWindow::Assembler` extension path is no
+longer an active API. Stateful Agent input is assembled through the canonical
+Journal → Context Policy → LLM Input Manifest pipeline.
+
 ### Optional dependencies
 
 Install additional gems only for the features you use:
@@ -179,7 +200,7 @@ class ResearchAgent < Phronomy::Agent::Base
   agent_definition id: "research-agent", version: 1
   model "gpt-4o"
   instructions "You are a research assistant. Use tools to answer questions."
-  tools WebSearch
+  tools(WebSearch => nil)
   max_iterations 5
 end
 
@@ -434,7 +455,7 @@ end
 class OrchestratorAgent < Phronomy::Agent::Base
   model "gpt-4o"
   instructions "Use the research tool first, then the write tool to produce a blog post."
-  tools ResearchTool, WriteTool
+  tools(ResearchTool => nil, WriteTool => nil)
 end
 
 result = OrchestratorAgent.new.invoke("Write a blog post about Ruby 3.4 features")
@@ -470,39 +491,56 @@ end
 > that logic must be implemented by the application. Reference implementations for
 > common patterns are available in `phronomy-examples` (example 06).
 
-### Knowledge — Static context injection
+### Knowledge — Persistent Agent context
+
+Knowledge is plain logical content retained by one Agent and considered by
+Context Policy for future LLM calls. It is not a separate source-object type and
+it is not automatically mandatory.
+
+Register initial Knowledge when creating the Agent:
 
 ```ruby
-# Static knowledge (policy files, reference docs)
-policy = Phronomy::Agent::Context::Knowledge::StaticKnowledge.new(
-  File.read("policy.md"),
-  type:   :policy,
-  source: "policy.md"   # exposed to LLM for citation
+policy_text = File.read("policy.md")
+
+agent = ResearchAgent.new(
+  knowledge: [
+    policy_text,
+    "Customer tier: enterprise"
+  ]
 )
+```
 
-# Inject at invocation time via the agent DSL
-class MyAgent < Phronomy::Agent::Base
-  model "gpt-4o-mini"
-  knowledge policy
-end
+Add durable Knowledge later:
+
+```ruby
+agent.add_knowledge(
+  "Customer locale: ja-JP",
+  metadata: {"origin" => "customer_profile"}
+)
 ```
 
-`static_knowledge_refresh!` invalidates the class-level cache of static knowledge sources.
-Call it when the underlying file or content has changed:
+Persistent Knowledge is Journal-backed, survives `Agent.load`, and is excluded
+from the public conversation transcript. `clear_knowledge!` logically
+invalidates earlier Knowledge while keeping the append-only Journal intact.
 
 ```ruby
-# Static knowledge sources are cached at the class level after the first fetch.
-# Call refresh! when the underlying content changes (e.g. after reloading policy.md).
-MyAgent.static_knowledge_refresh!
+agent.clear_knowledge!
 ```
 
-Load and split documents with built-in loaders:
+For request-scoped retrieval results that should not be persisted, use
+`before_llm_input` `segment_candidates` instead.
+
+Load and split documents with built-in loaders when the application needs an
+acquisition/RAG pipeline:
 
 ```ruby
 chunks = Phronomy::VectorStore::Loader::MarkdownLoader.new.load("docs/guide.md")
          .then { |docs| Phronomy::VectorStore::Splitter::RecursiveSplitter.new(chunk_size: 512).split(docs) }
 ```
 
+The application decides whether retrieved/extracted information becomes durable
+Agent Knowledge (`add_knowledge`) or per-call Context (`before_llm_input`).
+
 ### Multi-Agent Handoff — Hub-and-spoke routing
 
 ```ruby
@@ -601,9 +639,9 @@ When multiple hooks provide `model_config_patch`, patches are merged in hook
 order and later values win on key conflicts.
 
 `LLMInputPatch` can also supply `segment_candidates` for additional per-call
-context. Those segments participate in Manifest-first input assembly. This is
-intended for logical context supplied by the application; applications should
-not mutate RubyLLM message history directly.
+context. Those candidates enter the same Context Policy selection path as
+persistent/history candidates and are not automatically mandatory. They are
+not persisted to the Journal.
 
 ```ruby
 Phronomy::Agent::LLMInputPatch.new(
@@ -617,9 +655,9 @@ Phronomy::Agent::LLMInputPatch.new(
 )
 ```
 
-The Journal remains the canonical record of observed execution history.
-`before_llm_input` customizes the logical input assembled for a particular LLM
-call; it does not rewrite previously recorded Journal history.
+The Journal remains the canonical record of observed execution history and
+persistent Knowledge. `before_llm_input` customizes only the logical candidate
+set for a particular LLM call.
 
 ### GeneratorVerifier — Generator-Verifier loop with custom prompt builders
 
@@ -671,8 +709,7 @@ end
 
 ### MultiAgent::Orchestrator — Parallel subagent dispatch
 
-> **Note:** `dispatch_parallel` and `fan_out` use plain Ruby threads. Use
-> `max_concurrency:` to cap the number of concurrent workers and `on_error:`
+> **Note:** Use `max_concurrency:` to cap concurrent workers and `on_error:`
 > to control failure handling (`:raise` re-raises the first error after all
 > tasks complete; `:skip` fills failed slots with `nil`). For very large
 > fan-outs consider additional rate-limiting at the application level.
@@ -698,7 +735,6 @@ class MyOrchestrator < Phronomy::MultiAgent::Orchestrator
   instructions "Orchestrate."
 
   def run(query)
-    # Heterogeneous agents in parallel (cap at 4 threads; skip failures; 30 s timeout)
     results = dispatch_parallel(
       {agent: SearchAgent,   input: "topic A"},
       {agent: AnalysisAgent, input: query},
@@ -707,7 +743,6 @@ class MyOrchestrator < Phronomy::MultiAgent::Orchestrator
       timeout: 30
     )
 
-    # Fan-out — same agent, multiple inputs
     translations = fan_out(
       agent: TranslationAgent,
       inputs: %w[Hello World],
@@ -736,14 +771,10 @@ end
 app = Phronomy::Workflow.define(EnrichContext) do
   initial :enrich
   state :enrich, action: ->(s) do
-    # Use Thread#value to collect results safely — avoids concurrent Hash writes
     threads = {
       summary: Thread.new { Summarizer.call(s) },
       tags:    Thread.new { Tagger.call(s) }
     }
-    # For bounded waits, use Thread#join(timeout_seconds); nil means timed out — handle explicitly.
-    # Do not use Timeout.timeout or Thread#kill — both inject async exceptions that bypass cleanup.
-    # Prefer CancellationToken for cooperative cancellation of Phronomy-managed tasks.
     threads.each_value(&:join)
     s.merge(summary: threads[:summary].value, tags: Array(threads[:tags].value))
   end
@@ -756,12 +787,10 @@ state = app.invoke({}, config: { thread_id: "t1" })
 ### Output Parser — Structured LLM responses
 
 ```ruby
-# Extract JSON from LLM output (handles Markdown code fences automatically)
 parser = Phronomy::OutputParser::JsonParser.new
 data   = parser.parse('```json\n{"name":"Alice","score":0.9}\n```')
 # => { name: "Alice", score: 0.9 }
 
-# Map JSON directly to a Struct
 PersonSchema = Struct.new(:name, :age, keyword_init: true)
 parser = Phronomy::OutputParser::StructuredParser.new(PersonSchema)
 person = parser.parse('{"name":"Alice","age":30}')
@@ -784,15 +813,15 @@ runner  = Phronomy::Eval::Runner.new(
 results = runner.run(dataset, ->(q) { agent.invoke(q) })
 metrics = Phronomy::Eval::Metrics.new(results)
 
-puts "Mean score: #{metrics.mean_score}"   # Float 0.0–1.0
-puts "Pass rate:  #{metrics.pass_rate}"    # fraction with score >= threshold
+puts "Mean score: #{metrics.mean_score}"
+puts "Pass rate:  #{metrics.pass_rate}"
 ```
 
 ### Tracing — Custom observability
 
 ```ruby
 Phronomy.configure do |c|
-  c.tracer = MyCustomTracer.new  # any Phronomy::Tracing::Base subclass
+  c.tracer = MyCustomTracer.new
 end
 ```
 
@@ -840,10 +869,12 @@ persistence = Phronomy::Persistence::InMemory.new
 
 agent = ResearchAgent.create(
   agent_id: "research-session-42",
+  knowledge: ["Customer tier: enterprise"],
   persistence: persistence
 )
 
 agent.invoke("My name is Alice.")
+agent.add_knowledge("Customer locale: ja-JP")
 result = agent.invoke("What is my name?")
 
 puts result[:output]
@@ -869,6 +900,7 @@ Existing external conversation history can be supplied when a new Agent is creat
 ```ruby
 agent = ResearchAgent.create(
   context: existing_messages,
+  knowledge: initial_knowledge,
   persistence: persistence
 )
 ```
@@ -877,16 +909,14 @@ Imported history must satisfy Phronomy's Import contract. User, assistant, and T
 
 `thread_id` is an execution correlation identifier. It does not identify the persistent Agent and is not a substitute for `agent_id`.
 
-The current conversation or memory view can be advanced without deleting the canonical Journal:
+The active conversation and Knowledge views can be advanced independently without deleting the canonical Journal:
 
 ```ruby
-agent.clear_transcript!
-agent.clear_memory!
-agent.reset_context!
+agent.clear_transcript!  # conversation only
+agent.clear_knowledge!   # persistent Knowledge only
+agent.reset_context!     # both
 ```
 
-These operations change which historical records belong to the active context generation. The underlying append-only Journal remains intact.
-
 `purge!` is different: it permanently removes the Agent and its persisted execution history from the configured Persistence backend.
 
 ## Configuration
@@ -896,11 +926,11 @@ Phronomy.configure do |c|
   c.default_model                   = "gpt-4o-mini"
   c.recursion_limit                 = 25
   c.tracer                          = Phronomy::Tracing::NullTracer.new
-  c.before_llm_input                 = nil   # optional global before_llm_input hook
+  c.before_llm_input                = nil   # optional global before_llm_input hook
   c.trace_pii                       = false # default; set to true only when trace data contains no PII
   c.logger                          = nil   # optional; any object responding to #warn (e.g. Rails.logger)
   c.event_loop_stop_grace_seconds   = 5     # seconds to wait for sessions to drain on shutdown
-  c.runtime_backend                 = :thread   # :thread (default); :immediate (tests, synchronous); :fiber (experimental validation only); :cooperative (deprecated alias for :immediate)
+  c.runtime_backend                 = :thread   # :thread (default); :immediate (tests, synchronous); :fiber (experimental validation only)
   c.strict_runtime_guards           = false     # when true, raises SchedulerReentrancyError on invoke-inside-task
   c.stream_callback_error_policy    = :report   # :report (default) preserves Agent result; :fail_task fails Task with StreamCallbackError
 end
@@ -953,26 +983,20 @@ transition action.
 Phronomy detects this pattern automatically:
 
 ```ruby
-# Default (soft mode): logs a warning and continues
 Phronomy.configure { |c| c.strict_runtime_guards = false }
-
-# Strict mode: raises SchedulerReentrancyError immediately
 Phronomy.configure { |c| c.strict_runtime_guards = true }
 ```
 
 You can also query the current context directly:
 
 ```ruby
-Phronomy::Runtime.in_scheduler_context?  # => true if called from inside a task
+Phronomy::Runtime.in_scheduler_context?
 ```
 
 ### Migration: blocking wait → Task mapping
 
 ```ruby
-# Top-level synchronous use
 result = my_agent.invoke("Hello")
-
-# Explicit async from top-level code
 result = my_agent.invoke_async("Hello").wait_result
 ```
 
@@ -1064,7 +1088,7 @@ Task must not be returned from a Workflow entry or transition action.
 ### :immediate backend (synchronous / test mode)
 
 The `:immediate` backend runs tasks synchronously using `FakeScheduler`
-(backed by `Task::ImmediateBackend`).  Blocking I/O is isolated in `BlockingAdapterPool`.
+(backed by `Task::ImmediateBackend`). Blocking I/O is isolated in `BlockingAdapterPool`.
 To switch back to the default thread-per-task backend:
 
 ```ruby
@@ -1080,11 +1104,11 @@ end
 
 Phronomy uses a Manifest-first context architecture for stateful Agents.
 
-The main flow is:
-
 ```text
 Canonical Journal
       ↓
+Context candidates
+      ↓
 Context Policy
       ↓
 LLM Call Manifest
@@ -1094,17 +1118,34 @@ Runtime Projection
 RubyLLM / Provider
 ```
 
-The **Journal** is the canonical append-only record of logical execution facts observed by Phronomy.
+The **Journal** is the canonical append-only record of logical execution facts
+observed by Phronomy and persistent Knowledge explicitly registered by the
+application.
 
-The **Manifest** is the canonical logical input fixed for one particular LLM Call.
+The **Manifest** is the canonical logical input fixed for one particular LLM
+Call.
 
-Context-window management therefore does not trim or rewrite the Agent's canonical history. Instead, Phronomy selects the subset of available context needed for each LLM Call and records that selection in the Manifest.
+Context-window management therefore does not trim or rewrite the Agent's
+canonical history. Phronomy selects the subset of available optional Context
+needed for each LLM Call and records that selection in the Manifest.
 
-This distinction allows old history to remain available even when it does not fit in the current model's context window.
+Persistent Knowledge is an ordinary `:knowledge` Context candidate. It is not
+concatenated into the mandatory system prompt. Conversation history and
+Knowledge share the same policy/budget selection path while remaining distinct
+in public transcript semantics.
 
-Tool protocol dependencies are preserved during selection. For example, an assistant message containing Tool Calls and the corresponding Tool-role messages are selected as a protocol-safe unit rather than independently pruning messages in a way that would create an invalid LLM conversation.
+Per-call `before_llm_input` segment candidates also pass through Context Policy
+and are not written to the Journal.
 
-When the available budget is insufficient, optional historical context can be omitted from the current Manifest. Required context is never silently removed merely to satisfy the budget. If the required input cannot fit, Phronomy raises `ContextBudgetExceededError`.
+Tool protocol dependencies are preserved during selection. An assistant message
+containing Tool Calls and the corresponding Tool-role messages are selected as
+a protocol-safe unit rather than independently pruning messages in a way that
+would create an invalid LLM conversation.
+
+When the available budget is insufficient, optional history or Knowledge can be
+omitted from the current Manifest. Required context is never silently removed
+merely to satisfy the budget. If required input cannot fit, Phronomy raises
+`ContextBudgetExceededError`.
 
 ### Context-window configuration
 
@@ -1126,9 +1167,14 @@ end
 
 `max_output_tokens` reserves capacity for the model's output.
 
-The legacy `context_overhead` setting remains for compatibility with the legacy `build_context` path, but it is not the mechanism used to reserve system-prompt or Tool-definition space in Manifest-first context assembly. New Agent implementations should not rely on `context_overhead` for that purpose.
+Mandatory instructions, current input and Tool definitions are budgeted from
+their actual canonical values. `context_overhead` is not part of the current
+contract.
 
-The current default Context Policy is framework-managed. Public custom Context Policy APIs, deterministic persistent compaction, and other advanced policy extension points are still evolving and should not yet be treated as stable application APIs.
+The current default Context Policy is framework-managed. Public custom Context
+Policy APIs, deterministic persistent compaction, and other advanced policy
+extension points are still evolving and should not yet be treated as stable
+application APIs.
 
 > **Note on CJK languages**: The default `TokenEstimator` uses a character-ratio heuristic
 > calibrated for ASCII/Latin text (4 chars/token). For Chinese, Japanese, and Korean text,
@@ -1142,15 +1188,14 @@ The current default Context Policy is framework-managed. Public custom Context P
 > Phronomy::LlmContextWindow::TokenEstimator.tokenizer = ->(text) { enc.encode(text).length }
 > ```
 
-
 ### CancellationToken — Cooperative cancellation
 
 Pass a `CancellationToken` to any agent via `config: { cancellation_token: token }`.
 Cancellation is checked at multiple granular checkpoints: before the LLM call,
-after each streaming chunk, before each parallel
-tool-call batch, and after each `before_llm_input` hook. `CancellationError` is
-raised immediately. Phronomy does not replay the complete Agent invocation. No threads are force-killed — `ensure`
-blocks always execute.
+after each streaming chunk, before each parallel tool-call batch, and after each
+`before_llm_input` hook. `CancellationError` is raised immediately. Phronomy
+does not replay the complete Agent invocation. No threads are force-killed —
+`ensure` blocks always execute.
 
 > **Cooperative cancellation — not preemptive**
 >
@@ -1158,19 +1203,14 @@ blocks always execute.
 > checkpoints listed above; it is **not** injected as a signal into a running
 > operation. This means the following are **not** interrupted mid-execution:
 >
-> - A single `KnowledgeSource#fetch` that is already blocking (e.g. HTTP call)
+> - An application retrieval/load operation that is already blocking
 > - A single `chat.ask` call that is not streaming
 > - A single `tool.execute` call that is already running
 > - Any external I/O (database query, vector search, HTTP request) inside those calls
 >
-> For deep in-flight safety, complement `CancellationToken` with per-source or
-> per-tool timeouts. Prefer library-native timeouts such as `Net::HTTP#read_timeout`,
-> database `statement_timeout`, or Redis client timeout — these signal the I/O layer
-> to abort cleanly. Avoid `Timeout.timeout` unless you understand its async-exception
-> risks: it injects `Timeout::Error` at an arbitrary execution point (the same
-> mechanism as `Thread#kill`), which Phronomy avoids by default due to resource
-> safety concerns. Ruby's GVL prevents fully preemptive cancellation without such
-> risky interruption.
+> For deep in-flight safety, complement `CancellationToken` with operation-native
+> timeouts. Prefer library-native timeouts such as `Net::HTTP#read_timeout`,
+> database `statement_timeout`, or Redis client timeout.
 
 > **`timeout_after` vs `CancellationScope.deadline_in`**
 >
@@ -1196,18 +1236,16 @@ blocks always execute.
 > Phronomy does not interpret `config[:llm_timeout]`, `config[:tool_timeout]`,
 > Agent `retry_policy`, or Tool `retry_on`. Configure LLM transport behavior on
 > RubyLLM (or another adapter) and configure Tool transport behavior on the Tool's
-> HTTP/DB/MCP client. This ensures the layer capable of safely aborting the I/O owns
-> the timeout and retry semantics.
+> HTTP/DB/MCP client.
 >
 > `InvocationContext#deadline` and `cancellation_token` remain available for a
 > caller-defined root-operation boundary. They provide cooperative cancellation
 > across the Phronomy execution tree; they do not replace provider-native socket,
 > request, statement, or session timeouts.
->
+
 ```ruby
 token = Phronomy::Concurrency::CancellationToken.new
 
-# Cancel from another thread after 5 s
 Thread.new { sleep 5; token.cancel! }
 
 begin
@@ -1216,15 +1254,9 @@ rescue Phronomy::CancellationError
   puts "cancelled"
 end
 
-# Hard deadline via monotonic clock (recommended — immune to NTP/DST changes)
 token = Phronomy::Concurrency::CancellationToken.timeout_after(30)
 result = MyAgent.new.invoke("...", config: { cancellation_token: token })
 
-# Hard deadline via wall-clock (legacy — still supported)
-token = Phronomy::Concurrency::CancellationToken.new(deadline: Time.now + 30)
-result = MyAgent.new.invoke("...", config: { cancellation_token: token })
-
-# Propagate to all parallel workers via dispatch_parallel / fan_out
 token = Phronomy::Concurrency::CancellationToken.new
 Thread.new { sleep 10; token.cancel! }