Layered context memory revision 0

docs/agent-working-memory.md

@@ -0,0 +1,169 @@
+# Agent Working Memory Context Cache
+
+Date: 2026-05-04
+
+## Purpose
+
+Agent working memory packages are explicit, portable context bundles. They let
+an agent or user gather relevant Markdown knowledge, drop it when it is no
+longer needed, and reactivate it later by stable id.
+
+The implementation is local-first:
+
+- no live flex-auth requirement
+- no network access
+- no embedding or LLM provider requirement
+- no hidden memory writes
+- deterministic summaries first
+- optional local policy checks at package creation and activation
+
+## Core Objects
+
+| Object | Role |
+| --- | --- |
+| `MemoryNamespace` | Project, user, agent, thread, task, and custom namespace coordinates. |
+| `SourceSpan` | Path, snapshot id, unit kind/index, line span, selector, and engine. |
+| `ContextPackageItem` | One included memory item with text, summary, token estimate, policy, provenance, and metadata. |
+| `RetrievalRecipe` | Refreshable query/search recipe. |
+| `SummaryLayer` | Deterministic package summary layer. |
+| `ContextBudget` | Approximate max items/tokens and reserve. |
+| `ContextPackage` | Portable package envelope. |
+| `ContextActivation` | Activation/deactivation envelope with Markdown content and policy results. |
+| `LocalContextPackageRegistry` | Filesystem registry rooted at `.markitect/context`. |
+
+## Use Cases
+
+### Task Reactivation
+
+Create a package from the current workplan or architecture sections, then
+activate it in a later thread without rereading the whole repository.
+
+### Focused Code Review Context
+
+Pack only the sections, files, and examples relevant to a specific subsystem.
+Use a small token budget so activation produces a compact review bundle.
+
+### Project Onboarding
+
+Create a package with intent, scope, architecture, and current workplan
+summaries. A new agent can activate this instead of scanning every document.
+
+### Policy-Aware Knowledge Work
+
+Create and activate packages with local label policy. Package creation can
+filter sensitive sources, and activation can re-check whether the current
+subject may still read the items.
+
+### Identity-Like Continuity
+
+Represent durable collaboration norms or project principles as explicit
+namespace-scoped context packages. These are not hidden personality mutations;
+they are versioned and inspectable memory artifacts.
+
+### Mid-Term Episodic Memory
+
+Store decisions, explored alternatives, and task state for a thread or work
+session. Keep it separate from long term project memory so it can expire or be
+reviewed.
+
+## CLI
+
+Create from direct source files:
+
+```text
+mkt context pack "sections[heading=Decision]" --source docs/example.md
+```
+
+Create from the local index:
+
+```text
+mkt cache index docs --root .
+mkt context pack "sections[heading~=Policy]" --path docs/access-control-policy-gateway.md
+```
+
+Create from FTS search:
+
+```text
+mkt context pack "policy gateway" --search --limit 5
+```
+
+Activate:
+
+```text
+mkt context activate memory:package:... --target thread:wp-0008
+```
+
+Explain:
+
+```text
+mkt context explain memory:package:...
+```
+
+Refresh:
+
+```text
+mkt context refresh memory:package:...
+```
+
+Deactivate:
+
+```text
+mkt context deactivate memory:activation:...
+```
+
+## Manifest Shape
+
+```yaml
+title: Workplan context
+intent: Reactivate current workplan decisions.
+namespace:
+  project: markitect-tool
+  task: MKTT-WP-0008
+budget:
+  max_items: 4
+  max_tokens: 1200
+retrieval_recipes:
+  - kind: selector
+    query: sections[heading=Purpose]
+    engine: selector
+    sources:
+      - workplans/MKTT-WP-0008-agent-working-memory-context-cache.md
+```
+
+## Policy
+
+Policy metadata is copied from document frontmatter or the local index. When a
+local policy gateway is supplied, Markitect filters package items by the
+requested subject/action.
+
+Package creation typically uses action `package`; activation defaults to
+action `read`.
+
+External policy services may be attached later through the existing policy
+gateway boundary, but are not required.
+
+## Architecture Fit
+
+The memory layer is an internal extension over existing primitives:
+
+- local snapshots and FTS from `LocalSnapshotStore`
+- selectors and optional JSONPath from the query engines
+- local labels and trust zones from `LocalLabelPolicyGateway`
+- provenance, diagnostics, and capability metadata from the extension
+  framework
+
+It is deliberately separate from the dataflow workflow engine. Workflows
+orchestrate business processes; context packages capture reusable working
+memory for agents.
+
+## Future Extensions
+
+Natural extensions are intentionally deferred:
+
+- LLM-assisted summaries through an injected adapter
+- vector retrieval and embedding caches
+- decay/retention policies
+- reviewed long term identity packages
+- signed policy decisions and durable decision logs
+- remote or enterprise memory registries
+- package merge/diff and conflict diagnostics