# 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
- reasoning memory as decision graphs
- short-term memory as conversational event paths
- long-term memory as knowledge graphs
- memory service blueprints with size, latency, retention, refresh, compaction,
  and policy parameters
- signed policy decisions and durable decision logs
- remote or enterprise memory registries
- package merge/diff and conflict diagnostics

The graph/profile direction is captured in
`docs/agentic-memory-graph-blueprint-assessment.md` and
`MKTT-WP-0016: Agentic Memory Graphs And Service Blueprints`.