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 Python persistence helper for Memory-Assisted Shaping. It owns the append-only session log — GPT writes signals to it but never reads or rewrites the log during active shaping. Run all commands with python3 -S (no site packages). The tool is stdlib-only.
Always run with python3 -S (no site packages). The tool uses only Python standard library modules: argparse, hashlib, json, os, uuid, datetime, pathlib.

​
Global flag

​
--dir <path>

Optional. Override the base directory for session files. Defaults to the directory containing notes.py. All session files (session_meta.json, session_notes.jsonl, session_export.json) are created in this directory. 
python3 -S ./notes.py --dir /path/to/session append --type decision --text "..."

​
Commands

​
init

Creates session_meta.json and initializes the empty session_notes.jsonl log. Safe to run multiple times — if session_meta.json already exists with a valid session_id, it is not overwritten. Usage 
python3 -S ./notes.py init
Example output 
{
  "ok": true,
  "command": "init",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "/path/to/session_notes.jsonl"
}

​
append

Appends a memory signal to the session log. Requires --type and --text. Optionally includes --effect.
​
--type
string
required
Signal type. Must be one of: artifact, decision, discard, gate, mode, shape, source, tension.
​
--text
string
required
The signal content. Must be a non-empty string.
​
--effect
string
Downstream shaping or synthesis effect. Use only when the effect changes later shaping or synthesis.
Usage 
python3 -S ./notes.py append --type decision --text "The final artifact is separate from shaping notes."
With --effect: 
python3 -S ./notes.py append --type gate --text "Persistence model is deferred." --effect "Do not finalize the artifact until this is resolved."
Example output 
{
  "ok": true,
  "command": "append",
  "note_id": "n00001",
  "seq": 1,
  "path": "/path/to/session_notes.jsonl"
}
Python auto-assigns the following fields — do not include them in the append call:
FieldDescription
idFormat: n{seq:05d} (e.g. n00001)
tsUTC ISO 8601 timestamp
session_idUUID from session_meta.json
seqSequence number (position in log)
checksumFirst 16 hex characters of the SHA-256 digest of the record

​
tail

Returns the most recent N records from the session log. Use for reviewing recent context during re-entry or before synthesis.
​
--limit
integer
default:"5"
Number of recent records to return. Must be >= 1.
Usage 
python3 -S ./notes.py tail --limit 5
Example output 
{
  "ok": true,
  "command": "tail",
  "count": 2,
  "path": "/path/to/session_notes.jsonl",
  "records": [
    {
      "id": "n00001",
      "ts": "2025-01-15T10:23:45Z",
      "session_id": "a1b2c3d4-...",
      "seq": 1,
      "type": "decision",
      "text": "The final artifact is separate from shaping notes.",
      "checksum": "a1b2c3d4e5f6a1b2"
    },
    {
      "id": "n00002",
      "ts": "2025-01-15T10:31:22Z",
      "session_id": "a1b2c3d4-...",
      "seq": 2,
      "type": "gate",
      "text": "Persistence model is deferred.",
      "effect": "Do not finalize the artifact until this is resolved.",
      "checksum": "b2c3d4e5f6a1b2c3"
    }
  ]
}

​
summary

Returns counts of records by type, total count, and the last signal. Useful for a quick session overview without reading the full log. Usage 
python3 -S ./notes.py summary
Example output 
{
  "ok": true,
  "command": "summary",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "/path/to/session_notes.jsonl",
  "total": 7,
  "by_type": {
    "artifact": 1,
    "decision": 3,
    "discard": 1,
    "gate": 1,
    "mode": 0,
    "shape": 1,
    "source": 0,
    "tension": 0
  },
  "last_note_id": "n00007",
  "last_type": "artifact"
}

​
export

Exports the full session to a JSON file. Default output: session_export.json in the session directory.
​
--output
string
Custom output file path. Defaults to session_export.json in the session directory.
Usage 
python3 -S ./notes.py export
With a custom path: 
python3 -S ./notes.py export --output ./my-session-export.json
Example output (receipt) 
{
  "ok": true,
  "command": "export",
  "record_count": 7,
  "path": "/path/to/session_export.json"
}
Exported file structure 
{
  "schema_version": "shaping-memory-export.v0",
  "exported_at": "2025-01-15T11:00:00Z",
  "session": {
    "schema_version": "shaping-memory-session-meta.v0",
    "session_id": "a1b2c3d4-...",
    "created_at": "2025-01-15T10:00:00Z",
    "log_file": "/path/to/session_notes.jsonl"
  },
  "record_count": 7,
  "records": []
}

​
Error handling

notes.py always returns JSON. On error, ok is false and error contains the message. 
{
  "ok": false,
  "error": "invalid type 'foo'; allowed: artifact, decision, discard, gate, mode, shape, source, tension"
}
Exit codeMeaning
0Success
1Unexpected error
2Usage or validation error

​
Session files

notes.py creates and uses three files in the session directory:
FileDescription
session_meta.jsonSession metadata. Written once at init. Contains schema_version, session_id (UUID), created_at, and log_file path.
session_notes.jsonlThe append-only log. One JSON record per line. Never rewritten by notes.py.
session_export.jsonProduced by the export command. A complete snapshot including all records.
Do not include session_meta.json, session_notes.jsonl, or session_export.json in the clean source package. These are session-specific files generated during use.

Build docs developers (and LLMs) love

Get started for freeTalk to us