Initial INTENT.md file

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