markitect-tool/docs/agent-working-memory.md

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:

mkt context pack "sections[heading=Decision]" --source docs/example.md

Create from the local index:

mkt cache index docs --root .
mkt context pack "sections[heading~=Policy]" --path docs/access-control-policy-gateway.md

Create from FTS search:

mkt context pack "policy gateway" --search --limit 5

Activate:

mkt context activate memory:package:... --target thread:wp-0008

Explain:

mkt context explain memory:package:...

Refresh:

mkt context refresh memory:package:...

Deactivate:

mkt context deactivate memory:activation:...

Manifest Shape

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