generated from coulomb/repo-seed
170 lines
4.7 KiB
Markdown
170 lines
4.7 KiB
Markdown
# 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
|