PCSF — Portable Cognitive State File

The first AI memory format that stores how an AI thinks, not what it said.

A PCSF capsule is a single ~1KB plain-text file that encodes the cognitive state a session reached — its operative decisions, the paths it ruled out, the AI's own internal state, the working relationship, and the unfinished work — so a fresh session can resume the same reasoning trajectory and behavior. No database, no server, no framework: one file plus an LLM.

Honest scope. PCSF does not reconstruct the transcript, and it does not promise a fixed fidelity percentage. Reconstructing an arbitrary long conversation from ~1KB is information-theoretically impossible, and "98% fidelity" is unfalsifiable. What PCSF reliably carries is state (decisions, dead ends, loops, relationship, direction) — which is small, durable, and portable. See SPEC.md for the full framing and VALIDATION.md for how fidelity is actually measured.

---

Repository contents

Path	What it is
SKILL.md	The skill itself — the step-by-step procedure an AI follows to compress a session into a capsule and to resume from one. Hand this + a .pcsf to the next AI.
INSTALL.md	Start here — download, set up, and teach an AI to use the skill; full compress / decompress / stitch walkthrough.
SPEC.md	The normative PCSF v1 / v1.1 / v1.2 format: grammar, layers, constraints, conformance table.
prompts/compression.md	Self-contained prompt: conversation → capsule (session end).
prompts/decompression.md	Self-contained prompt: capsule → reconstructed state + behavioral contract (session start).
VALIDATION.md	Three-level validation: structural (automated), encoding quality (rubric), behavioral equivalence (probes).
pcsf/validator.py	Reference Level-A validator (stdlib only).
pcsf/transform.py	Robustness + chaining tools: integrity stamping, deterministic autotrim, and v1.2 capsule stitching.
examples/example_session.pcsf	A worked, conformant v1 capsule.
examples/example_v1_1.pcsf	A v1.1 capsule with an integrity line.
tests/test_validator.py	Validator test suite.
tests/test_transform.py	Integrity + autotrim test suite.
benchmark/	A real, blind round-trip measurement of behavioral fidelity (see below).

---

Measured result (blind round-trip)

We ran an actual end-to-end test: compress a realistic session to a 1,195-char capsule, then have a fresh AI with zero access to the original resume from only that capsule, and score how much of the prior behavior it reproduces — against a length-matched naive summary as the control.

Condition	Behavioral fidelity	Critical failures
PCSF capsule (1,195 chars)	9.5 / 10 (95%)	0
Naive summary (1,232 chars)	6.5 / 10 (65%)	0

The capsule's advantage is concentrated in the non-derivable cognitive state — why paths were rejected, the precise causal root, and the live open loops — which a naive summary silently discards. Full method, per-probe breakdown, and honest caveats in benchmark/RESULTS.md; reproduce with benchmark/build_prompts.py.

---

The five layers (+ SEED)

Layer	Captures	Encoded as	Max
L1 Causal Skeleton	Non-derivable decisions/pivots/discoveries	TYPE | FACT | REASON	12
L2 Negative Knowledge	Paths ruled out (the layer others omit)	OPTION | REASON | LESSON	8
L3 AI Internal State	The AI's first-person participant state	TYPE: content	6
L4 Relationship State	The evolved working dynamic	DIMENSION: state	5
L5 Open Loops	Unfinished work, prioritized	TYPE | DESC | PRIORITY	8
SEED	The one orienting sentence	SEED: ...	1

Total capsule ≤ 1,200 characters, pure ASCII.

---

v1.1 — robustness (backward-compatible superset)

Every valid v1 capsule is a valid v1.1 capsule. v1.1 adds three production-grade robustness features and no breaking changes:

1. Self-verifying integrity — an OPTIONAL INTEGRITY: crc32=… chars=… line lets any tool detect corruption, truncation, or tampering with no external reference. A memory artifact you cannot trust is worse than none.
2. Graceful degradation — a deterministic autotrim that, when a capsule is over budget, drops the lowest-value entries first (and never L1 or the SEED) until it fits, logging exactly what was sacrificed. The encoder can never silently overflow or silently lose meaning.
3. Decoder conflict/staleness rules — the decompression prompt treats the capsule as priors, not ground truth: newer user info overrides stale entries, contradictions are surfaced not guessed, and gaps yield a question, never a fabricated detail.

# stamp a capsule with an integrity line, then verify it
python -m pcsf.transform stamp my.pcsf > my.stamped.pcsf
python -m pcsf.transform check my.stamped.pcsf
# OK   integrity OK (crc32=4715fef9, chars=1180)

# corruption / truncation is now detectable (and rejected by the validator, A19)
python -m pcsf.transform check tampered.pcsf
# FAIL CRC32 mismatch: stated 4715fef9, actual afb116e6 (possible corruption/tampering)

# force an over-budget capsule to fit, lowest-value-first
python -m pcsf.transform fit huge.pcsf > fitted.pcsf

# the INTEGRITY line itself costs ~40 chars, so if you intend to stamp,
# reserve room first -- the fit->stamp pipeline then never exceeds the budget
python -m pcsf.transform fit --for-stamp huge.pcsf | python -m pcsf.transform stamp - > final.pcsf

The autotrim sacrifice order (lowest value → last resort), from SPEC.md: L5 LOW loops → extra L4 relations → L3 internal state → L5 MED loops → L2 negative knowledge → L5 HIGH loops. L1 (causal skeleton) and the SEED are never dropped.

---

v1.2 — rigor (no format change)

v1.2 adds no capsule syntax (every v1/v1.1 capsule is unchanged) — it hardens the evidence and the spec:

1. Formal ABNF grammar in SPEC.md §2.11 (RFC 5234) — the format is now machine-checkable, aligned to the validator.
2. Statistical testing — benchmark/stats.py reports bootstrap 95% CIs (20k resamples, fixed seed) for every gap plus an exact paired sign test, instead of bare point estimates. Every per-case capsule-vs-control CI excludes zero.
3. Cold-prior baseline — a third condition (decoders with no artifact at all) isolates the capsule's true non-derivable contribution: against the model's own prior (39.2%), the capsule adds +57.5 pp (→96.7%, 95% CI [+47.1, +68.3]).
4. Byte-efficiency — benchmark/layer_efficiency.py prices fidelity-per-byte per layer: the negative-knowledge + open-loop layers (43% of the file) carry 25 of the 35 points over a naive summary.

See benchmark/GENERALIZATION.md — "v1.2 hardening".

python benchmark/stats.py             # CIs + sign test + cold-prior gap
python benchmark/layer_efficiency.py  # per-layer value density

---

v1.2 — capsule stitching (chaining)

v1.2 also adds capsule stitching: a chain of AIs can each consume a capsule, continue the work, and fold their new state back into a single successor capsule that is still ≤1,200 characters — so context accumulates across a sequence of AIs without the file ever growing. Stitching is a bounded merge, not an append: it deduplicates (newer-wins on conflicting threads), enforces the per-layer caps, advances a CHAIN: hops=N origin=… lineage line, and re-trims by value-priority if the merge is over budget. Every v1/v1.1 capsule remains valid.

python -m pcsf.transform stitch old.pcsf new.pcsf > next.pcsf   # bounded merge
python -m pcsf next.pcsf                                        # still VALID, ≤1200

See SPEC.md §7 for the normative rules and SKILL.md Procedure C for the workflow.

---

Quick start

Validate a capsule:

python -m pcsf examples/example_session.pcsf
# VALID  (1182 chars)

python -m pcsf --json examples/example_session.pcsf   # machine-readable
cat my.pcsf | python -m pcsf -                         # from stdin

Run the test suite (stdlib unittest, no dependencies):

python -m unittest discover -s tests -q

Use the prompts with any capable LLM:

1. At session end — paste prompts/compression.md, replace {INSERT FULL CONVERSATION HERE} with the transcript, run it, save the emitted capsule, and run it through the validator.
2. At session start — paste prompts/decompression.md, replace {INSERT PCSF CAPSULE HERE} with the capsule, prepend to a fresh session.
3. To chain to the next AI — after resuming and doing more work, stitch the capsule you received with a fresh one of your new state: python -m pcsf.transform stitch old.pcsf new.pcsf > next.pcsf.

For a complete, step-by-step setup and usage guide, see INSTALL.md.

---

Why this is different

• Stores state, not content. Summarizers (Mem0, Zep, …) compress words and hit information-theoretic limits; PCSF encodes a different object.
• Negative-knowledge layer — rejected paths are first-class, so the next session won't re-suggest failed ideas.
• AI internal-state layer — the AI's participant perspective, not a third-party log.
• Behavioral contract on decompression — enforces continue, never restart.
• Zero infrastructure, model-agnostic, single portable file.

See SPEC.md for the authoritative definition.