Layered context memory revision 0

docs/agent-working-memory-thought-experiment.md

@@ -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.