generated from coulomb/repo-seed
250 lines
8.2 KiB
Markdown
250 lines
8.2 KiB
Markdown
---
|
|
id: MKTT-WP-0008
|
|
type: workplan
|
|
title: "Agent Working Memory Context Cache"
|
|
domain: markitect
|
|
status: done
|
|
owner: markitect-tool
|
|
topic_slug: markitect
|
|
planning_priority: complete
|
|
planning_order: 90
|
|
depends_on_workplans:
|
|
- MKTT-WP-0006
|
|
- MKTT-WP-0007
|
|
- MKTT-WP-0009
|
|
created: "2026-05-03"
|
|
updated: "2026-05-04"
|
|
state_hub_workstream_id: "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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
id: MKTT-WP-0008-T006
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "2f18386c-9d2c-4af1-b8e2-75cb487c1692"
|
|
```
|
|
|
|
Add:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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.
|