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 exposes five commands. During live shaping, append is used by default. tail, summary, and export are readback commands and should only be run when explicitly needed — not automatically on every turn.

​
init

Initialize a new session. Creates session_meta.json and an empty session_notes.jsonl. If a session already exists, reads and validates the existing meta without overwriting it. 
python3 -S ./notes.py init
No parameters beyond the optional global --dir. Example output 
{
  "ok": true,
  "command": "init",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "/path/to/session_notes.jsonl"
}

​
append

Append a memory signal to the session log. This is the primary live command used during shaping. 
python3 -S ./notes.py append --type <type> --text "<text>" [--effect "<effect>"]
​
--type
required
Signal type. Must be one of: artifact, decision, discard, gate, mode, shape, source, tension. No other values are valid in V0.
​
--text
required
The signal text. Must be a non-empty string.
​
--effect
Describes how the signal affects later shaping or synthesis. Omit if not needed. Only included in the stored record when provided.
Examples 
python3 -S ./notes.py append --type decision --text "The final artifact is separate from shaping notes."
Example output 
{
  "ok": true,
  "command": "append",
  "note_id": "n00001",
  "seq": 1,
  "path": "/path/to/session_notes.jsonl"
}
Python automatically adds id, ts, session_id, seq, and checksum to each stored record. GPT only provides type, text, and optionally effect. Never send a schema-complete record during live append.

​
tail

View the most recent N notes from the session log. 
python3 -S ./notes.py tail [--limit <n>]
​
--limit
default:"5"
Number of records to return. Must be >= 1. Defaults to 5.
Example 
python3 -S ./notes.py tail --limit 3
Example output 
{
  "ok": true,
  "command": "tail",
  "count": 2,
  "path": "/path/to/session_notes.jsonl",
  "records": [
    {
      "id": "n00001",
      "ts": "2024-01-15T10:30:00Z",
      "session_id": "a1b2c3d4-...",
      "seq": 1,
      "type": "decision",
      "text": "The final artifact is separate from shaping notes.",
      "checksum": "a1b2c3d4e5f6a7b8"
    }
  ]
}
Use tail only during readback — when OP requests a recap, or synthesis preparation requires consolidated state. Do not run it automatically every turn.

​
summary

Return a count of notes by type, plus the last note’s ID and type. 
python3 -S ./notes.py summary
No parameters beyond the optional global --dir. Example output 
{
  "ok": true,
  "command": "summary",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "/path/to/session_notes.jsonl",
  "total": 5,
  "by_type": {
    "artifact": 1,
    "decision": 2,
    "discard": 0,
    "gate": 1,
    "mode": 0,
    "shape": 1,
    "source": 0,
    "tension": 0
  },
  "last_note_id": "n00005",
  "last_type": "artifact"
}
summary is the preferred readback command before SYNTHESIS. It gives a fast structural overview without reading every record. Run tail only if you also need the recent record content.

​
export

Export the full session — metadata plus all records — to a single JSON file. 
python3 -S ./notes.py export [--output <path>]
​
--output
Path to write the export file. Defaults to session_export.json next to notes.py.
Example 
python3 -S ./notes.py export --output ./my-session-export.json
Example output 
{
  "ok": true,
  "command": "export",
  "record_count": 5,
  "path": "/path/to/session_export.json"
}
Use export only for OP-requested export, handoff, or full session consolidation. The export file (session_export.json) is a derived view and should not be committed as part of the clean source package.

​
Global flag: —dir

--dir overrides the default base directory where session files are read from and written to. It must be placed before the subcommand: 
python3 -S ./notes.py --dir /custom/path append --type decision --text "..."
The default base directory is the directory containing notes.py itself. --dir is optional — most sessions do not need it.
V0 assumes one active writer per directory. Do not use the same --dir value from multiple concurrent processes. Concurrent writers are not protected against in V0.

Build docs developers (and LLMs) love

Get started for freeTalk to us