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.

notes.py is the persistence layer for Memory-Assisted Shaping. It owns all memory file management — GPT emits minimal signals, and Python appends, timestamps, assigns IDs, and checksums each record deterministically. GPT never generates these fields, and never rewrites or reads live memory files outside of an explicit readback operation.

​
Design principles

  • Append-only: no existing records are ever rewritten during live shaping
  • Stdlib-only: runs with python3 -S (no site packages, no external dependencies)
  • Deterministic: Python adds id, timestamp, session_id, sequence number, and checksum — GPT never generates these
  • Minimal trust: Python does not infer meaning, reshape content, or decide importance
  • Single writer: V0 assumes one active writer per package directory

​
What Python does NOT do

notes.py has deliberate non-responsibilities that keep the live shaping boundary clean:
  • Does not infer shaping meaning from signal content
  • Does not reshape or normalize content
  • Does not rewrite prior live records
  • Does not read note files during live append
  • Does not summarize the log after append

​
Running notes.py

All commands are run with the -S flag: 
python3 -S ./notes.py <command>
Always use python3 -S, not plain python3. The -S flag disables site packages and ensures stdlib-only execution. Using plain python3 violates the execution contract.

​
Output format

All commands return JSON to stdout. On success, ok is true. On error, ok is false and error contains the message. 
{
  "ok": false,
  "error": "invalid type 'note'; allowed: artifact, decision, discard, gate, mode, shape, source, tension"
}

​
Storage location

By default, session files are written next to notes.py. Use --dir to override: 
python3 -S ./notes.py --dir /path/to/session append --type decision --text "..."
--dir is a global flag and must come before the subcommand. Placing it after the subcommand name will cause a parse error.

Command reference

Full reference for all five notes.py commands with flags, output shapes, and examples.

Session files

Structure, location, and source-control guidance for the three generated session files.

Build docs developers (and LLMs) love

Get started for freeTalk to us