From bd104ca3ced7ac1654e0a4f05e86dd88745443b1 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 4 May 2026 23:48:16 +0200 Subject: [PATCH] Initial INTENT.md file --- INTENT.md | 270 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 270 insertions(+) create mode 100644 INTENT.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..6777dfa --- /dev/null +++ b/INTENT.md @@ -0,0 +1,270 @@ +# INTENT + +## Purpose + +`phase-memory` exists to provide a **profile-driven memory infrastructure for +agentic systems**, spanning memory concepts from ephemeral and fluid working +context to durable, stabilized long-term memory. + +The project owns the sophisticated memory runtime boundary that should not live +inside `markitect-tool`: memory graphs, event paths, stores, compaction, +retention, service profiles, operational planning, and adapters for advanced +memory backends. + +The core idea is that agentic memory is not one thing. It should be organized +into phases with different speed, cost, durability, confidence, and governance +expectations. + +## Primary Utility + +The repository should provide infrastructure to model, instantiate, operate, +and inspect memory systems with explicit operational parameters. + +Primary memory forms: + +- **Reasoning memory** based on decision graphs +- **Short-term memory** based on conversational paths and event logs +- **Long-term memory** based on knowledge graphs +- **Activation memory** based on bounded context packages +- **Identity and preference memory** based on reviewed, durable records + +The system should make it possible to describe a desired memory setup as a +blueprint or profile, including: + +- enabled memory kinds +- backing stores and adapters +- maximum nodes, edges, events, packages, bytes, and tokens +- p50/p95 read and write latency targets +- retention, deletion, and decay rules +- compaction and summarization strategies +- freshness and refresh triggers +- merge and conflict policies +- policy reauthorization requirements +- observability events +- failure and fallback behavior + +## Memory Phases + +`phase-memory` should treat memory as a lifecycle, not a pile of saved text. + +### Ephemeral Memory + +Immediate working state used during a single task, tool call, or reasoning +step. It should be fast, cheap, discardable, and explicitly scoped. + +### Fluid Memory + +Short-lived conversational or task memory that may branch, merge, compact, or +be discarded. It captures paths through conversation, tool use, observations, +interruptions, plan changes, and context activations. + +### Stabilized Memory + +Reviewed or repeated knowledge that has earned durability. It may become part +of a project knowledge graph, a decision record, a preference record, or an +identity memory. Stabilized memory must preserve provenance, confidence, +freshness, and policy metadata. + +### Rigid Long-Term Memory + +Durable memory that should change only through explicit migration, review, +versioning, or policy-governed update. This includes long-lived project facts, +important decisions, trusted source relationships, stable user preferences, and +governed knowledge assets. + +## Core Concepts + +### Reasoning Graphs + +Reasoning memory captures how an agent arrived somewhere: + +- questions +- hypotheses +- claims +- assumptions +- evidence +- alternatives +- decisions +- rejected paths +- outcomes +- risks +- follow-up obligations + +It should support queries such as: + +- why was this decision made? +- what assumptions does it depend on? +- what evidence supports or contradicts it? +- which outcomes invalidated previous reasoning? +- which artifacts are affected by this decision? + +### Conversational Paths + +Short-term memory captures the navigable shape of an interaction: + +- user turns +- agent turns +- plans +- tool calls +- observations +- edits +- validations +- interruptions +- branches and merges +- activations and deactivations + +It should not be limited to transcript storage. It should model which path led +to current state, what branches were abandoned, which facts remain active, and +what should be compacted or discarded. + +### Knowledge Graphs + +Long-term memory captures stable knowledge: + +- entities +- artifacts +- concepts +- capabilities +- people and roles +- decisions +- contracts +- policies +- preferences +- source-backed facts + +Every node and edge should support provenance, confidence, freshness, +namespace, source spans, and policy metadata. + +### Context Packages + +Context packages are activation artifacts: bounded, inspectable payloads that +can be loaded into an agent's working context. + +`phase-memory` should be able to compile graph neighborhoods, decision paths, +conversation episodes, and knowledge slices into activation packages. It should +also be able to consume package formats produced by adjacent tools such as +`markitect-tool`. + +## Relationship To Markitect + +`markitect-tool` is the markdown-facing syntax and contract layer. It should +describe, validate, and consume memory systems through markdown-friendly +profiles, manifests, provenance expectations, adapter descriptors, and +deterministic context-package compilation. + +`phase-memory` is the memory operating layer. It should implement and operate +the richer runtime: + +- graph and event models +- memory stores +- compaction and stabilization +- lifecycle policy +- service blueprint instantiation +- operational diagnostics +- retrieval and activation planning +- adapters to external graph, vector, LLM, policy, and audit systems + +The boundary should stay clean: + +- Markitect owns markdown-native interface contracts. +- `phase-memory` owns memory service behavior. +- Markitect may validate and emit memory blueprints. +- `phase-memory` may execute, store, compact, and serve them. +- Both sides should interoperate without making either repository a hidden + dependency of the other. + +## Strategic Role + +`phase-memory` should become the memory infrastructure layer for agentic +systems in the wider Net-Kingdom ecosystem. + +It should be able to run: + +- standalone for local development and testing +- embedded behind a local agent toolchain +- as a service with durable stores +- as an adapter layer over existing systems + +It should integrate cleanly with: + +- `markitect-tool` for markdown-native contracts and context packages +- future knowledge-system runtimes for persistence and orchestration +- policy infrastructure such as `flex-auth` where enterprise access control is + required +- graph databases, vector stores, LLM providers, and audit sinks through + optional adapters + +## Strategic Boundaries + +This repository is **not** intended to be: + +- a generic note-taking application +- a chat transcript archive +- a markdown authoring toolkit +- a full identity or authorization platform +- a generic vector database +- a provider-specific LLM memory plugin +- a domain-specific knowledge model + +It should provide the memory framework and runtime contracts that let those +systems cooperate. + +## Design Principles + +- **Memory has phases** + Treat ephemeral, fluid, stabilized, and rigid memory differently. + +- **Graphs over blobs** + Preserve relationships, provenance, and evolution instead of storing only + flattened summaries. + +- **Profiles over hidden defaults** + Memory behavior should be described through explicit blueprints with size, + latency, retention, compaction, and policy parameters. + +- **Local-first, service-ready** + The first useful path should work without external infrastructure, but the + architecture should support durable service deployments. + +- **Inspectable activation** + Agents should know what memory was activated, why it was selected, where it + came from, and what policy checks applied. + +- **Deterministic core, assisted extensions** + Graph operations, validation, retention, and package compilation should have + deterministic local behavior. LLM extraction, embeddings, and summarization + should remain optional adapters. + +- **Policy-aware by design** + Memory nodes, edges, events, and activations should carry enough metadata to + support reauthorization, audit, redaction, and trust-zone boundaries. + +- **Interoperability before lock-in** + The project should support external stores and engines without forcing one + canonical backend too early. + +## Maturity Target + +A mature `phase-memory` should provide: + +- canonical memory graph and event schemas +- local durable stores for development and small deployments +- memory service blueprint/profile validation +- graph/event query and explanation APIs +- compaction and stabilization workflows +- graph-to-context-package compilers +- retention and deletion lifecycle enforcement +- observability and diagnostics for memory operations +- optional adapters for graph databases, vector stores, LLM extraction, + enterprise policy decision points, remote registries, and audit sinks +- clear interoperability contracts with `markitect-tool` and adjacent + Net-Kingdom infrastructure + +## Stability Note + +Changes to this file define the project boundary for `phase-memory`. + +The boundary should evolve deliberately. The central commitment is that +`phase-memory` owns sophisticated agentic memory runtime concerns, while +markdown-native authoring and contract surfaces remain the responsibility of +adjacent tools such as `markitect-tool`.