phase-memory/INTENT.md

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