Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xxyoudeadpunkxx/memory-assisted-shaping/llms.txt

Use this file to discover all available pages before exploring further.

Memory-Assisted Shaping is built on three discrete layers that each own a specific responsibility. GPT follows the behavioral contract defined in protocol.md — reading before shaping, shaping before synthesis. Python (notes.py) owns append-only persistence and is the only component that writes to memory files. note-io.md defines the strict I/O boundary between them, specifying what GPT may emit, when it may emit it, and how Python handles the record. None of these layers substitute for another: GPT never writes memory files, and Python never infers meaning or decides importance.

​
GPT’s role

GPT operates as a structural shaping engine. Its job is to take ambiguous input and turn it into operational form without premature synthesis, unsupported diagnosis, or decorative expansion. The three-step ordering is non-negotiable:
  1. Read — understand the input before shaping it.
  2. Shape — consolidate form, resolve gates, and prepare an artifact path before writing.
  3. Synthesize — produce the final artifact only after explicit operator approval.
GPT emits minimal memory signals when continuity would degrade without retention. It does not manage, rewrite, or normalize memory files. Final artifacts are produced only after the operator explicitly approves synthesis — implied momentum, positive feedback, and silence are not approval.

​
Python’s role

Python owns append-only persistence. When GPT emits a memory signal, Python does the following:
  • Adds a unique id, ts (timestamp), session_id, seq (sequence number), and checksum to the signal.
  • Appends the completed record to session_notes.jsonl.
  • Returns a short receipt to GPT.
Python does not infer meaning from the signal text, reshape signal content, or decide whether a signal is important. Those responsibilities belong to GPT and the protocol. Python appends deterministically and stays out of the shaping loop.

​
The I/O boundary

note-io.md defines the contract that keeps shaping and file management cleanly separated. The key rules:
  • Live memory is write-only from the model’s perspective during shaping. GPT does not read the log on every turn.
  • Emit means command execution, not chat text. A memory signal is a python3 -S ./notes.py append call, not a note written in the conversation.
  • Readback is explicit. Summary, tail, and export commands run only when the operator requests a recap, a checkpoint is needed, re-entry requires state recovery, or synthesis preparation requires consolidated state.
This boundary prevents the conversation from becoming file management and keeps OP-facing shaping output minimal and direct.

​
Session lifecycle

1

Session entry

GPT reads protocol.md and note-io.md, locates notes.py, and runs python3 -S ./notes.py init if Python execution is available. If Python is unavailable, GPT states once that append-only persistence is not active. GPT then enters READING_ALIGNMENT. Session entry does not repeat on every turn.
2

Reading and shaping

GPT understands the input, separates declared from inferred material, detects candidate form, exposes material tension, and identifies real gates. When the shape can be consolidated without final artifact production, GPT transitions to SHAPING. Memory signals are emitted only when omitting them would lose critical continuity — not for ordinary conversation or cosmetic details.
3

Gate handling

At each real gate, GPT classifies before acting. The four strategies are ASK, PROPOSE, DEFER, and STOP — chosen based on whether the gate affects operator intent, reversibility, or artifact correctness. Deferred gates are tracked and revisited before synthesis. They are never treated as closed.
4

Synthesis approval

The operator explicitly approves artifact production. GPT does not enter SYNTHESIS based on positive feedback, session momentum, or silence. Before non-trivial synthesis, GPT runs readback to confirm consolidated state. An approved mode transition signal is appended when Python persistence is active.
5

Final artifact

GPT produces a clean, standalone artifact from consolidated form. The artifact contains no process notes, raw memory signals, discarded paths, shaping rationale, or conversation history. It is proportionate, operational, and usable without reinterpretation.

​
Protocol-only mode

When Python execution is unavailable, the protocol still operates in full. GPT states once at session entry that append-only persistence is not active and continues shaping. Gate handling, state transitions, output discipline, and synthesis approval all remain in effect. GPT does not claim memory is persisted, does not write memory signals in chat as a substitute, and does not allow the absence of Python to change the behavioral contract in any other way.

Operating states reference

The three explicit states that gate session phases, what triggers each, and what is forbidden in each.

Gate handling

How decision points are classified as real gates and which of the four handling strategies to apply.

Memory signals

When to emit memory signals, which types exist, and how they flow from GPT to Python.

Authority order

The precedence order GPT follows when instructions, sources, signals, and inference conflict.

Build docs developers (and LLMs) love

Get started for freeTalk to us