generated from coulomb/repo-seed
Layered context memory revision 0
This commit is contained in:
104
docs/agent-working-memory-thought-experiment.md
Normal file
104
docs/agent-working-memory-thought-experiment.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# Agent Working Memory Thought Experiment
|
||||
|
||||
Date: 2026-05-04
|
||||
|
||||
## Prompt
|
||||
|
||||
Imagine an agent memory architecture optimized for short and mid term
|
||||
efficiency across different reaction speeds, timescales, and cost constraints,
|
||||
while preserving a personality-like long term identity and learning memory that
|
||||
evolves over time.
|
||||
|
||||
This is a wishful design note. It is not a promise that every layer belongs in
|
||||
`markitect-tool` core.
|
||||
|
||||
## Memory Layers
|
||||
|
||||
| Layer | Reaction Speed | Lifetime | Cost Shape | Useful Contents |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Reflex context | milliseconds to seconds | one response | highest compute pressure | current user turn, active file, tool output, immediate errors |
|
||||
| Working set | seconds to minutes | one task step | medium compute pressure | current plan, nearby code/docs, selected snippets, constraints |
|
||||
| Episode memory | minutes to hours | one chat/thread/work session | moderate storage | decisions, explored dead ends, task state, user preferences for this effort |
|
||||
| Project semantic memory | hours to weeks | project lifecycle | cheap local storage, occasional refresh | architecture docs, stable APIs, workplans, policies, source maps, examples |
|
||||
| Identity and learning memory | weeks to years | agent/persona/project relationship | expensive to write, cheap to retrieve | values, style, durable preferences, repeated collaboration patterns |
|
||||
| Policy and safety memory | all speeds | explicit freshness windows | must be rechecked before use | labels, trust zones, subject identity, decision ids, authorization context |
|
||||
|
||||
The main design pressure is not just retrieval quality. It is deciding when a
|
||||
memory should be cheap, fast, provisional, discardable, re-checkable, or
|
||||
durable.
|
||||
|
||||
## Wish List
|
||||
|
||||
If a few things could be manifested instantly:
|
||||
|
||||
1. A hot context router would keep the current working set small and sharp. It
|
||||
would load exact spans and summaries only when they are needed, then release
|
||||
them when the task moves on.
|
||||
2. Every context item would carry provenance, policy metadata, freshness,
|
||||
token cost, and a reason it was included.
|
||||
3. Memory would be layered, not monolithic. Fast scratch memory, package memory,
|
||||
project memory, and identity memory would have different write thresholds.
|
||||
4. Durable memory writes would be explicit and inspectable. The agent could
|
||||
propose "this seems worth remembering" rather than silently mutating itself.
|
||||
5. Long term identity would be represented as small, versioned principles and
|
||||
preferences, not as a bag of transcripts.
|
||||
6. The system would support both activation and forgetting. Dropping context
|
||||
should be as first-class as loading it.
|
||||
7. Retrieval would be policy-aware at both package creation and activation.
|
||||
A package created yesterday should not be blindly activated today.
|
||||
8. Summaries would be multi-resolution: one-line, section-level, package-level,
|
||||
project-level, and identity-level, each with its own freshness and source
|
||||
links.
|
||||
9. Local deterministic memory would work offline. LLM-assisted summaries,
|
||||
embeddings, external stores, and enterprise authorization would be optional
|
||||
adapters.
|
||||
10. The agent could maintain a small "self continuity" layer: tone,
|
||||
collaboration norms, current mission, and durable lessons, all with user
|
||||
review and rollback.
|
||||
|
||||
## Dynamic Balances
|
||||
|
||||
The useful architecture has several moving balances:
|
||||
|
||||
- Fast recall vs. exact provenance: the reflex layer can be approximate, but
|
||||
activation packages must be explainable.
|
||||
- Rich context vs. token budget: every item needs a token estimate and a
|
||||
summary so a caller can choose the right resolution.
|
||||
- Stability vs. freshness: project architecture memory is useful only if it
|
||||
can be refreshed against current snapshots.
|
||||
- Personalization vs. consent: long term identity memory should require higher
|
||||
write friction than task-local memory.
|
||||
- Local autonomy vs. enterprise control: local package creation must work
|
||||
offline, while activation can re-check policy when a gateway is available.
|
||||
- Retrieval breadth vs. actionability: packages should be small enough to
|
||||
activate directly and large enough to explain why they matter.
|
||||
|
||||
## Implications For Markitect
|
||||
|
||||
Markitect should own the local, inspectable package layer:
|
||||
|
||||
- schema for context packages
|
||||
- package creation from selectors, search, and manifests
|
||||
- deterministic summary layers
|
||||
- activation/deactivation/refresh/explain lifecycle
|
||||
- source spans, token estimates, provenance, and policy metadata
|
||||
- optional adapter boundaries for assisted summaries, embeddings, vector
|
||||
stores, and external policy decision points
|
||||
|
||||
Markitect should not own hidden agent identity memory as an ambient service.
|
||||
It can provide explicit package formats and namespaces for identity-like
|
||||
memory, but durable writes should remain visible, reviewable, and policy-bound.
|
||||
|
||||
## Best First Step
|
||||
|
||||
The first implementation should be boring in the right way:
|
||||
|
||||
- local files and local SQLite index only
|
||||
- deterministic summaries only
|
||||
- explicit package files in `.markitect/context`
|
||||
- policy metadata preserved and optionally rechecked
|
||||
- no live flex-auth, vector database, embedding provider, LLM provider, or
|
||||
hidden agent state
|
||||
|
||||
That gives future systems a trustworthy memory substrate without making the
|
||||
core repo pretend to be a full cognitive architecture.
|
||||
169
docs/agent-working-memory.md
Normal file
169
docs/agent-working-memory.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# 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
|
||||
@@ -40,7 +40,7 @@ and descriptions mirror the operational view.
|
||||
| `MKTT-WP-0009` | complete | done | `MKTT-WP-0006` | Access-controlled knowledge gateway is complete: local labels, trust zones, path rules, policy-aware cache query/search, decisions, diagnostics, and external adapter boundaries. |
|
||||
| `MKTT-WP-0014` | complete | done | `MKTT-WP-0009` | Markitect-side enterprise IAM access-control integration is complete: NetKingdom/key-cape-compatible identity claims, flex-auth resource/policy contract, directory group resolution fixtures, decision-log sink, workflow declarations, CLI commands, and external PDP request examples. |
|
||||
| `MKTT-WP-0012` | complete | done | `MKTT-WP-0004`, `MKTT-WP-0010`, `MKTT-WP-0011` | Document function layer is complete: deterministic Markdown-native function descriptors, registry, inline/fenced syntax, pipelines, context bindings, CLI, docs, examples, diagnostics, provenance, and extension descriptor. |
|
||||
| `MKTT-WP-0008` | P3 | todo | `MKTT-WP-0006`, `MKTT-WP-0007`, `MKTT-WP-0009` | Agent working-memory cache after backend and policy floor are available. |
|
||||
| `MKTT-WP-0008` | complete | done | `MKTT-WP-0006`, `MKTT-WP-0007`, `MKTT-WP-0009` | Agent working-memory context cache is complete: context package schema, local registry, package creation from queries/search/manifests, deterministic summaries, namespaces, activation/deactivation/refresh/explain lifecycle, policy re-checks, CLI, docs, and examples. |
|
||||
| `MKTT-WP-0015` | P2 | todo | `MKTT-WP-0010`, `MKTT-WP-0011`, `MKTT-WP-0012` | Future render and document-function extensions: typed values, richer syntax, document-local reusable functions, Quarkdown/export adapters, render-aware references, assets, and permission sandboxing. Defer unless publishing/export pressure becomes current. |
|
||||
|
||||
## Dependency Notes
|
||||
@@ -91,8 +91,8 @@ protocols. A live flex-auth service can improve enterprise deployment, central
|
||||
policy administration, and durable audit, but it is not a prerequisite for the
|
||||
document function layer or local agent context packages.
|
||||
|
||||
Remaining Markitect workplans, including `MKTT-WP-0008` and the future
|
||||
`MKTT-WP-0015` extension track, should keep this policy posture:
|
||||
Remaining Markitect workplans, including the future `MKTT-WP-0015` extension
|
||||
track, should keep this policy posture:
|
||||
|
||||
- use `AccessPolicyGateway`, `PolicySubject`, `PolicyObject`, and
|
||||
`PolicyDecision` as local contracts
|
||||
@@ -103,6 +103,12 @@ Remaining Markitect workplans, including `MKTT-WP-0008` and the future
|
||||
parsing, deterministic functions, workflows, cache queries, or context
|
||||
package lifecycle
|
||||
|
||||
`MKTT-WP-0008` completed the local agent working-memory package layer. It
|
||||
deliberately implements explicit, inspectable context packages rather than
|
||||
hidden ambient agent memory. LLM-assisted summaries, embeddings, vector stores,
|
||||
remote registries, retention/decay, and reviewed long-term identity packages
|
||||
remain future optional extensions.
|
||||
|
||||
## State Hub Mirror
|
||||
|
||||
Native State Hub dependency edges should mirror the whole-workstream
|
||||
|
||||
Reference in New Issue
Block a user