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.

During a shaping session, notes.py generates three files. These are session-specific and should not be committed as part of the clean source package.
Do not include generated session files in the clean source package. Add the following entries to .gitignore:
session_meta.json
session_notes.jsonl
session_export.json

​
Default file locations

By default, all files are written next to notes.py: 
memory-assisted-shaping/
  notes.py
  session_meta.json       ← generated
  session_notes.jsonl     ← generated
  session_export.json     ← generated (only after export command)
Use --dir to write session files to a different directory. See the command reference for details.

​
session_meta.json

Created by init. Holds session identity for the duration of the shaping session. 
{
  "schema_version": "shaping-memory-session-meta.v0",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2024-01-15T10:00:00Z",
  "log_file": "/path/to/session_notes.jsonl"
}
If session_meta.json already exists when init runs, it is validated — not overwritten. A missing or invalid session_id field raises an error and halts the command.

​
session_notes.jsonl

The append-only live log. Each line is a compact JSON record. Records are never rewritten or removed. 
{"id":"n00001","ts":"2024-01-15T10:05:00Z","session_id":"a1b2...","seq":1,"type":"shape","text":"Idea is a behavioral protocol for ChatGPT Projects.","checksum":"a1b2c3d4e5f6a7b8"}
{"id":"n00002","ts":"2024-01-15T10:10:00Z","session_id":"a1b2...","seq":2,"type":"gate","text":"Persistence model is deferred.","effect":"Do not finalize until resolved.","checksum":"c3d4e5f6a7b8c9d0"}
Record fields
FieldDescription
idZero-padded note ID (e.g. n00001)
tsUTC timestamp in ISO 8601 format
session_idUUID sourced from session_meta.json
seq1-based sequence number
typeOne of the eight allowed signal types
textThe signal text
effect(Optional) Only present when provided via --effect
checksumFirst 16 hex characters of the SHA-256 of the record, computed before the checksum field is added

​
session_export.json

Produced by the export command. Contains session metadata plus all records from the live log in a single JSON document. 
{
  "schema_version": "shaping-memory-export.v0",
  "exported_at": "2024-01-15T11:00:00Z",
  "session": { "...session_meta fields..." },
  "record_count": 5,
  "records": [ "...all records from jsonl log..." ]
}
The export file is a derived view. session_notes.jsonl is the persistence source of truth. Do not treat session_export.json as canonical — re-run export to regenerate it if needed.

​
Atomic writes

notes.py uses atomic writes for JSON files: it writes to a .tmp file, flushes, calls fsync, then renames the temporary file into place. The JSONL log uses append plus fsync per record. This protects against file corruption from interrupted writes — a partial write to the temporary file will not replace the prior valid file.

Command reference

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

Back to Quickstart

Return to the quickstart guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us