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.