markitect-tool/docs/agentic-memory-graph-blueprint-assessment.md

# Agentic Memory Graph Blueprint Assessment

Date: 2026-05-04

## Question

Can the current Markitect memory framework naturally extend into a system with:

- reasoning memory based on decision graphs
- short-term memory based on conversational paths
- long-term memory based on knowledge graphs

And can it do so efficiently by generating profiles or blueprints that describe
the services, sizes, response times, retention rules, and policy constraints
needed for a given agent memory deployment?

## Short Answer

Yes, but not directly as-is.

The current `markitect_tool.memory` layer is a strong first layer for explicit
activation packages. It gives us source spans, namespaces, summaries, budgets,
provenance, freshness, local policy metadata, activation lifecycle, and
refreshable retrieval recipes.

That is enough to be the **payload and activation layer** for agent memory.

It is not yet enough to be the **memory operating model**. A three-part memory
system needs graph schemas, event logs, service blueprints, operational
profiles, lifecycle policies, and graph-aware retrieval/compaction.

## Three Memory Systems

### A. Reasoning Memory: Decision Graphs

Reasoning memory should store how the agent got somewhere:

- claims
- assumptions
- decisions
- rejected alternatives
- tradeoffs
- evidence links
- unresolved questions
- confidence
- reversibility
- affected artifacts
- follow-up obligations

The natural shape is a directed graph:

```text
question -> hypothesis -> evidence -> decision -> action -> outcome
                       \-> rejected alternative -> reason
```

This differs from a context package. A package captures selected content for
activation. A decision graph captures the evolution of reasoning and can later
answer:

- why did we choose this?
- what alternatives were considered?
- which assumptions are stale?
- what decision depends on this source?
- which outcomes invalidated prior reasoning?

Current fit:

- `ContextPackageItem.provenance` can point to reasoning nodes later.
- `RetrievalRecipe` can reactivate relevant decision subgraphs.
- `MemoryNamespace` can scope decisions to project/thread/task.

Missing:

- node and edge schema for reasoning graphs
- evidence/claim/decision/outcome types
- graph integrity rules
- graph query and explanation API
- compaction from detailed reasoning paths into durable decision summaries

### B. Short-Term Memory: Conversational Paths

Short-term memory should store the navigable shape of an interaction:

- turns
- tool calls
- observations
- plan changes
- branch points
- interruptions
- user corrections
- local state transitions
- activation/deactivation events

The natural shape is an event path with branches:

```text
turn -> plan -> tool_call -> observation -> edit -> validation
                     \-> interruption -> revised plan
```

This is not merely chat history. A useful conversational memory stores which
path led to the current state, which branches were abandoned, and which facts
are still active.

Current fit:

- `ContextActivation` can be logged as a path event.
- `ContextPackage` can represent a compact episode summary.
- `MemoryNamespace.thread` and `MemoryNamespace.task` already provide useful
  coordinates.

Missing:

- event envelope for turns, tools, observations, decisions, and activations
- path compaction into episode packages
- active/inactive fact tracking
- branch/merge semantics
- retention windows and discard rules
- low-latency current-thread profile

### C. Long-Term Memory: Knowledge Graphs

Long-term memory should store stable project or identity knowledge:

- entities
- concepts
- artifacts
- people/roles
- contracts
- APIs
- decisions
- policies
- relationships
- durable preferences
- source-backed facts

The natural shape is a knowledge graph with provenance and policy on every
node and edge:

```text
artifact -> implements -> capability
decision -> affects -> module
user_preference -> applies_to -> interaction_style
policy_label -> governs -> source_span
```

Current fit:

- local index and source spans give us source-backed evidence.
- content classes and references already hint at entity/relationship modeling.
- packages can activate graph neighborhoods.

Missing:

- canonical knowledge node/edge vocabulary
- extraction pipeline from Markdown/reference/content-class/query outputs
- stable entity identity and merge rules
- confidence and freshness tracking
- graph-backed retrieval recipes
- profile-driven storage adapters

## Efficient Instantiation Through Profiles

A useful memory framework should let a project generate a blueprint such as:

```yaml
id: markitect-agent-memory
intent: Support project implementation agents with local-first memory.
profiles:
  reasoning:
    store: local-sqlite-graph
    max_nodes: 50000
    p95_read_ms: 50
    retention: project
    compaction:
      mode: decision-summary
      max_tokens_per_decision: 300
  conversation:
    store: local-event-log
    hot_window_turns: 40
    p95_read_ms: 20
    retention: 14d
    branch_policy: preserve_decision_branches
  knowledge:
    store: local-property-graph
    max_nodes: 250000
    p95_neighborhood_ms: 150
    embedding_adapter: optional
    refresh: on_snapshot_change
policy:
  activation_requires_recheck: true
  default_action: read
  external_pdp: optional
outputs:
  context_packages:
    max_tokens: 6000
    max_items: 40
```

Such a profile should not necessarily start services by itself. The first
Markitect version should validate, normalize, and explain these profiles, then
emit implementation manifests for local or external runtimes.

## Operational Parameters To Model

Every profile should be able to state:

- target memory kind: reasoning, conversation, knowledge, package, identity
- backing store kind and adapter id
- maximum nodes, edges, events, packages, and bytes
- target p50/p95 read and write latency
- token budget for activation
- freshness and refresh triggers
- retention and deletion rules
- compaction policy
- merge/conflict policy
- policy reauthorization requirements
- observability events
- failure modes and fallback behavior
- export/import requirements

This gives memory architecture a concrete shape instead of a vague promise of
"more context."

## Architecture Extension

The current framework can extend naturally if we add four layers:

1. **Memory Graph Model**
   Shared node, edge, graph snapshot, and graph query envelopes.

2. **Memory Event Log**
   Append-only event model for conversation paths, activations, reasoning
   transitions, and graph updates.

3. **Memory Service Blueprint**
   Declarative profile that captures service topology, operational limits,
   latency targets, storage budgets, retention, compaction, and policy.

4. **Graph-To-Package Compiler**
   Deterministic compiler that turns graph neighborhoods, decision paths, and
   conversation episodes into `ContextPackage` objects.

## Recommendation

Create a follow-on workplan for **Agentic Memory Graphs And Service
Blueprints**.

Do not replace the current context package layer. It remains the right
activation artifact. The next layer should make packages graph-aware and
profile-driven.

The first implementation should stay local and deterministic:

- YAML blueprint validation
- graph/event dataclasses
- local SQLite graph/event prototype or interface-first fake store
- package compilation from graph neighborhoods
- CLI inspection and planning commands
- no mandatory LLM, embedding, vector database, or external policy service

## What To Defer

- autonomous long-term personality mutation
- unsupervised durable preference writes
- live vector search
- graph embeddings
- remote graph service orchestration
- distributed memory synchronization
- enterprise authorization administration

Those are valuable later, but they should plug into a clean profile/adapter
model rather than becoming assumptions in core.