markitect-tool/workplans/MKTT-WP-0008-agent-working-memory-context-cache.md

id, type, title, domain, status, owner, topic_slug, planning_priority, planning_order, depends_on_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	created	updated	state_hub_workstream_id
MKTT-WP-0008	workplan	Agent Working Memory Context Cache	markitect	done	markitect-tool	markitect	complete	90	MKTT-WP-0006 MKTT-WP-0007 MKTT-WP-0009	2026-05-03	2026-05-04	6269f338-4f5c-40ee-90e5-0371f5c3874c

MKTT-WP-0008: Agent Working Memory Context Cache

Purpose

Create activatable context packages that let agents drop, reactivate, and reuse project knowledge efficiently while preserving provenance and policy metadata.

Thought Experiment And Design Refinement

The implementation was preceded by a wishful architecture pass documented in docs/agent-working-memory-thought-experiment.md.

The useful model is layered memory:

• reflex context for the current response
• short working set for the active task
• episodic memory for a thread or work session
• project semantic memory for architecture and source knowledge
• identity-like continuity memory for durable principles and preferences
• policy/safety memory that must be rechecked before activation

The key refinement is that Markitect should implement the local, explicit, inspectable package layer rather than hidden ambient agent memory. Long-term identity and learning memory can be represented as reviewed namespace-scoped packages later, but writes should remain visible and reversible.

This shaped the implementation:

• package creation and activation are explicit CLI/library operations
• every item carries source spans, summaries, token estimates, provenance, and policy metadata
• deterministic summaries come first
• package creation and activation can both run local policy checks
• local files and the local SQLite index are enough for the first version
• LLM summaries, embeddings, remote registries, retention/decay, and durable identity packages remain future optional extensions

Implementation Summary

Implemented the first local agent working-memory context cache:

• markitect_tool.memory extension package with context package schema, retrieval recipes, budgets, namespaces, summary layers, activation envelopes, and filesystem-backed local registry.
• Package creation from direct Markdown source queries, local index selector or JSONPath queries, FTS search results, and YAML manifests.
• Deterministic summaries and approximate token estimates.
• Activation, deactivation, refresh, explain, list, and save/load lifecycle.
• Optional local policy filtering at package creation and activation.
• CLI commands under mkt context.
• Built-in extension descriptor memory.context-package.
• Documentation and example manifest in docs/agent-working-memory.md, docs/agent-working-memory-thought-experiment.md, and examples/memory/workplan-context.manifest.yaml.

Architectural Boundary

This workplan depends only on Markitect-local backend and policy contracts:

• ContextPackageRegistry
• LocalSnapshotStore and query/search result envelopes
• AccessPolicyGateway
• PolicySubject, PolicyObject, and PolicyDecision
• local label policy and deterministic enterprise-policy fixtures

It must not require flex-auth, NetKingdom SSO, Keycloak, Entra, OpenFGA, OPA, Cedar, or any other live service. Those systems may attach later through optional policy adapters. The local implementation should remain useful for single-user and team-local agent memory.

For enterprise deployments, a context package may store optional external policy references such as policy version, decision id, resource id, issuer, or freshness metadata. These references are metadata, not hard dependencies.

P8.1 - Define context package schema

id: MKTT-WP-0008-T001
status: done
priority: high
state_hub_task_id: "21ee9c37-4add-4886-bd03-a7bb4b20e957"

Represent source spans, summaries, token estimates, freshness, provenance, policy labels, and retrieval recipes.

The schema should include optional policy metadata:

• policy labels and trust zones
• subject or namespace that created the package
• policy decision ids where available
• policy version or local policy id
• external resource ids where available
• refresh and reauthorization requirements

These fields must support local policy gateways first and external policy services only through optional adapters.

Implemented: ContextPackage, ContextPackageItem, SourceSpan, RetrievalRecipe, SummaryLayer, ContextBudget, and MemoryNamespace define the local schema. Package items preserve source spans, summaries, token estimates, provenance, freshness, and policy metadata.

P8.2 - Implement package creation from queries

id: MKTT-WP-0008-T002
status: done
priority: high
state_hub_task_id: "4df06b93-13ce-41fb-a8c3-f04d4ad9d752"

Create context packages from simple selectors, cached search results, or manifest files.

Package creation should use current query/search APIs and policy-aware result filtering. It should not call flex-auth directly; future flex-auth-backed filtering can be injected through the existing policy gateway boundary.

Implemented: packages can be created from direct Markdown source queries, local indexed selector/JSONPath queries, FTS search results, and YAML manifests. Optional local policy gateways filter package items using the existing LocalLabelPolicyGateway boundary.

P8.3 - Implement activation lifecycle

id: MKTT-WP-0008-T003
status: done
priority: medium
state_hub_task_id: "9f3d9792-d655-482d-bae0-262df5fc0136"

Support activate, deactivate, refresh, and explain operations for a package.

Activation should re-check local policy metadata when a policy gateway is available. In the absence of an external service, activation remains fully local and explainable.

Implemented: activate_context_package, deactivate_context_package, refresh_context_package, explain_context_package, and LocalContextPackageRegistry support the lifecycle locally. Activation rebuilds summaries after policy filtering so denied content does not leak through package-level summaries.

P8.4 - Add memory namespaces

id: MKTT-WP-0008-T004
status: done
priority: medium
state_hub_task_id: "2d090494-0e10-44cd-8e2d-c418d7530b27"

Support project, user, agent, thread, and task namespaces without hard-coding any external agent platform.

Namespace design should leave room for enterprise subject ids and external resource ids, but must not require any particular SSO, IAM, or authorization provider.

Implemented: MemoryNamespace supports project, user, agent, thread, task, and custom namespace fields without depending on any external agent platform.

P8.5 - Add summary layers

id: MKTT-WP-0008-T005
status: done
priority: medium
state_hub_task_id: "4d1cf970-3d6d-4bd5-8da9-ec2399aa7efe"

Support deterministic summaries first, then optional LLM-generated summaries through an injected adapter.

Assisted summaries must be optional and policy/capability-gated before any prompt assembly happens.

Implemented: deterministic extractive/count summaries are included. Assisted summaries remain a documented future adapter path and are not invoked by core package creation or activation.

P8.6 - Add CLI commands

id: MKTT-WP-0008-T006
status: done
priority: medium
state_hub_task_id: "2f18386c-9d2c-4af1-b8e2-75cb487c1692"

Add:

mkt context pack <manifest-or-query>
mkt context activate <package-id>
mkt context explain <package-id>
mkt context refresh <package-id>

CLI commands should work against local packages without flex-auth. Optional policy flags may accept local policy files or later external adapter configuration.

Implemented:

mkt context pack
mkt context activate
mkt context deactivate
mkt context explain
mkt context refresh
mkt context list

Commands work with local package files and the .markitect/context registry. Policy flags use local label policy only; external policy systems remain optional adapters.

Exit Criteria

• Agents can reactivate project context by stable id.
• Context packages show included sources and token budgets.
• Memory writes remain explicit and inspectable.
• Local policy metadata and explanations are preserved without external services.
• flex-auth or other enterprise policy services remain optional adapter paths, not prerequisites.