generated from coulomb/repo-seed
108 lines
4.0 KiB
Markdown
108 lines
4.0 KiB
Markdown
# Phase Memory Boundary
|
|
|
|
Date: 2026-05-05
|
|
|
|
This note defines how `kontextual-engine` should relate to the sibling
|
|
`phase-memory` project while closing the current persistence gap.
|
|
|
|
## Source Scope
|
|
|
|
`phase-memory` exists to provide profile-driven memory infrastructure for
|
|
agentic systems. Its intent covers memory phases, memory graphs, event paths,
|
|
stores, compaction, retention, service profiles, activation planning, and
|
|
adapters for advanced memory backends.
|
|
|
|
`kontextual-engine` exists to provide an AI-first, headless knowledge and
|
|
content engine. Its intent covers persistent knowledge artifacts, collections,
|
|
relationships, ingestion, workflow state, query, service access, and agent-
|
|
operable knowledge processes.
|
|
|
|
The projects overlap around durable state, graph-shaped records, context
|
|
packages, provenance, and agent operation. They must stay separated by purpose.
|
|
|
|
## Ownership Boundary
|
|
|
|
`kontextual-engine` owns:
|
|
|
|
- Persistent knowledge collections, artifacts, relationships, and revisions.
|
|
- Content identity, artifact metadata, source provenance, and lifecycle state.
|
|
- Durable workflow run records and operation manifests.
|
|
- Query and retrieval over knowledge artifacts and relationships.
|
|
- Service and programmatic APIs for operating knowledge systems.
|
|
- Adapter surfaces that can call `markitect-tool`, `phase-memory`, storage
|
|
backends, and future workflow engines.
|
|
|
|
`phase-memory` owns:
|
|
|
|
- Ephemeral, fluid, stabilized, and rigid memory phase semantics.
|
|
- Reasoning graphs, conversational paths, activation memory, identity memory,
|
|
preference memory, and reviewed memory records.
|
|
- Memory profiles with latency, token, byte, retention, decay, compaction,
|
|
freshness, merge, conflict, and policy parameters.
|
|
- Memory-specific lifecycle enforcement, including retention, deletion,
|
|
stabilization, compaction, and summarization.
|
|
- Memory retrieval planning and activation-package compilation.
|
|
- Adapters to graph databases, vector stores, audit sinks, policy systems, and
|
|
memory-specific backend infrastructure.
|
|
|
|
## Interop Boundary
|
|
|
|
`kontextual-engine` may persist memory-related artifacts when they are treated
|
|
as knowledge assets, such as:
|
|
|
|
- reviewed decisions,
|
|
- source-backed facts,
|
|
- durable project context packages,
|
|
- workflow outputs,
|
|
- policy-visible provenance records,
|
|
- exported memory graph slices.
|
|
|
|
It should not implement memory-specific behavior such as:
|
|
|
|
- conversational path branching and merge semantics,
|
|
- memory decay and retention policy execution,
|
|
- compaction or summarization strategies,
|
|
- activation planning heuristics,
|
|
- preference or identity memory governance,
|
|
- graph/vector memory backend selection,
|
|
- memory service profile validation.
|
|
|
|
Those behaviors belong to `phase-memory`. `kontextual-engine` should integrate
|
|
with them through explicit adapters and stable exchange formats.
|
|
|
|
## Persistence Implication
|
|
|
|
The persistence gap in `kontextual-engine` should be closed as durable knowledge
|
|
runtime storage, not as a general memory runtime.
|
|
|
|
The first durable backend should persist:
|
|
|
|
- collections,
|
|
- artifacts,
|
|
- artifact revisions,
|
|
- relationships,
|
|
- workflow runs,
|
|
- run manifests,
|
|
- change records,
|
|
- queryable metadata,
|
|
- context-package references.
|
|
|
|
It should not persist phase-memory internals beyond opaque references or
|
|
exported artifacts unless an integration adapter explicitly maps them.
|
|
|
|
## Integration Shape
|
|
|
|
The preferred integration shape is:
|
|
|
|
1. Core `kontextual-engine` repository contracts remain independent.
|
|
2. A future `phase-memory` adapter can read/write durable knowledge artifacts
|
|
through those contracts.
|
|
3. Context packages can move between the systems as inspectable payloads.
|
|
4. Memory-specific policies stay in `phase-memory`; knowledge persistence
|
|
policy stays in `kontextual-engine`.
|
|
5. Cross-repo references should use stable identifiers, content digests, and
|
|
provenance metadata rather than implicit filesystem coupling.
|
|
|
|
This keeps `kontextual-engine` focused on persistent, operable knowledge while
|
|
leaving sophisticated agentic memory behavior to the project designed for it.
|