A local, SQLite-backed PGX instrument for conversational LLMs doing durable, structured knowledge work.
Parmesan helps a human collaborator and an LLM build, inspect, and maintain an authoritative semantic graph. It is designed to be handed directly to a capable conversational LLM: no hosted service, plugin framework, or bundled corpus is required.
From an extracted release or a source checkout:
python PARMESAN_LLM.py doctor
python PARMESAN_LLM.py catalog --profile coreThen read these in order:
M2_SEMANTIC_VIRTUAL_INFRASTRUCTURE.md— canonical Method 2 semantic virtual infrastructure.M3_VIEW_ALGEBRA.md— canonical Method 3 view algebra, dependent on M2.docs/PARMESAN_4_QUICKSTART.md— new PM4 managed workspaces, composition, and migration.docs/SEMANTIC_CAPSULES.md— safe complete-head and selective-piece sharing between conversations.START_HERE.md— zero-context operating path and compatibility tools.docs/OPERATIONAL_PHILOSOPHY.md— authority, evidence, lineage, session machinery, sentinels, and handoff.docs/CONSTRUAL_ENGINEERING.md— the 4C model and PGX practice for meaning-sensitive work.
Use Parmesan when an LLM needs to repeatedly add artifacts, ask questions, generate synthesis, conduct experiments, and preserve durable semantic outcomes as a structured corpus.
- The SQLite database is the authoritative semantic graph and the default handoff artifact.
- PGX, Markdown, reports, and knowledge-base views are materialized projections: generate or cache them when useful, but do not mistake them for the source of truth.
- Persistent pointers, append-only revisions, exact local Markdown links, transactions, validation, full-text search, and audit history make the corpus inspectable and revisable.
- Parallel work receives automatic corpus, semantic-snapshot, workstream, and materialization identities. Parmesan identifies divergence; the operating LLM performs semantic reconciliation deliberately.
Parmesan is not a corpus, a web service, an autonomous agent, or a framework that every session must extend. Session-specific machinery for PDFs, OCR, extraction, or experiments may be useful, but only durable results and selected provenance belong in the graph.
Construal Engineering is the deliberate use of PGX to compose, preserve, inspect, compare, and revise the conditions through which material is taken to mean something for a task. It is grounded in the four-part model of composition, compilation, connotation, and construal.
The normal semantic-link form is:
[natural-language anchor](POINTER)The pointer is an exact, case-sensitive identity in the active corpus—not a URL, file path, or network target. For traversal work, use pgx.traversal.embed with either direct traversal notation or a structured ternary tree. Direct notation may contain one, two, three, or many ordered terms and may be nested; it is not constrained to operand–operator–operand shape. Parmesan resolves pointers and serializes lawful notation such as:
[((C1):(O1):(C2)):(O2):(C3)]
Read docs/CONSTRUAL_ENGINEERING.md and its two required 4C source documents before authoring or interpreting traversal expressions. Parmesan guarantees syntax, identity, revisions, and validation; an LLM remains responsible for contextual interpretation and for preserving meaningful alternative construals.
Use the core tools to initialize a database, create graphs and nodes, retrieve bounded context, revise nodes with optimistic concurrency, and validate the resulting database. The intended Python entrance is:
from parmesan import catalog, dispatch, doctor, initialize_corpus, open_corpusInitialization returns an embedded corpus head. Every later mutation must explicitly supply that value as expected_head, then carry the successful response's new head into the next request. Parmesan does not infer write authority from a filesystem path. Missing or stale heads fail without mutation, preventing stale live-chat context or a copied path from silently targeting the wrong database state.
For MIC work, pgx.workspace.initialize is the preferred starting point. It declares exactly one authoritative database and separates resources, machinery, projections, scratch work, and handoffs. pgx.workspace.inspect rejects unregistered SQLite candidates rather than guessing which same-named file is current.
When a coherent pass may outlive one chat turn, pgx.change_set.open persists its intent and base head. Related mutation requests carry the change-set ID and receive ordered compact receipts. The work can be rediscovered with pgx.change_set.list and resumed with pgx.change_set.show; publication remains blocked until every open change set is explicitly resolved.
For an already-decided cluster, pgx.batch.preflight validates up to 50 node, revision, traversal, and relation operations with zero persistent writes. pgx.batch.apply then commits all members or none, advances one authority head, and records one compact change-set receipt when attached. Semantic selection remains the LLM's responsibility.
Legacy or project-extended corpora are adopted with pgx.workspace.adopt, never migrated in place. Adoption records the untouched source hash and preserved semantic counts, and requires explicit classification of every private table. Registered extension schema fingerprints are checked before mutation, so unknown tables or machinery/schema drift cannot silently fall outside corpus authority.
For PM4 conversations, the normal handoff is now a resource-thin semantic capsule:
parmesan pm4 inspect my-workspace
parmesan pm4 share my-workspace \
--expected-workspace WORKSPACE_UUID \
--expected-snapshot SNAPSHOT_UUID \
--expected-sequence SEQUENCE
parmesan pm4 receive PARMESAN_PM4_SHARE_….zip --output received-workspace
parmesan pm4 orient received-workspaceshare captures the complete committed semantic head through SQLite's backup
API, cold-validates it, excludes live journal sidecars and local machinery, and
returns one attachment path plus its SHA-256. Registered historical resources
are carried as detached identity descriptors rather than copied wholesale. A
received workspace remains valid and semantically operable while reporting
resource hydration separately. This remains the whole-workspace handoff; 4.2's
selective piece workflow below is the smaller alternative.
When the other conversation needs only part of the workspace, plan and share a selective piece instead:
parmesan pm4 plan-piece my-workspace --root GRAPH_OR_NODE \
--expected-workspace WORKSPACE_UUID --expected-snapshot SNAPSHOT_UUID \
--expected-sequence SEQUENCE
parmesan pm4 share-piece my-workspace --root GRAPH_OR_NODE \
--expected-workspace WORKSPACE_UUID --expected-snapshot SNAPSHOT_UUID \
--expected-sequence SEQUENCEParmesan recursively carries graph members and exact node-pointer dependencies, preserves branch-scoped identities, and withholds the artifact if a semantic pointer is missing or ambiguous. The recipient can inspect the attachment without writing, receive it as a small PM4 workspace, and use ordinary PM4 composition to combine it with another workspace. Exact identities already present are deduplicated; aliases are never treated as global identity.
Ordinary work remains in the default working mode and never automatically rebuilds or serializes an external knowledge base. When a clean database copy or another publication surface is explicitly needed, use pgx.mode.set to enter publish mode before invoking the advanced materialization tools. Publish mode freezes semantic mutation so each output comes from one fixed database state. Return to working mode afterward.
A materialization receives its own identity while retaining its corpus and semantic-snapshot lineage. Use lineage comparison when independently continued copies need deliberate LLM reconciliation.
Managed workspaces provide the safer normal path: pgx.handoff.publish performs one bounded, atomic database-plus-receipt publication and returns the source to working mode automatically. pgx.handoff.inspect compares corpus identity, embedded head, lineage, byte hash, and machinery identity; filenames and volatile attachment paths confer no authority.
For a directory containing an authoritative Parmesan database plus projections or resources:
parmesan corpus check /path/to/corpus
parmesan corpus release /path/to/corpus --patch --output-dir /path/to/releasesThe release command stages a clean copy, removes transients, runs declared checks, builds a deterministic ZIP, and validates the delivered artifact. It does not modify the source corpus. See docs/CORPUS_OPERATIONS.md.
| Read when you need to… | Document |
|---|---|
| Operate Parmesan with minimal prior context | START_HERE.md |
| Apply the canonical M2 and M3 virtual-workspace methods | M2, then M3 |
| Start, fork, compose, or migrate a PM4 workspace | docs/PARMESAN_4_QUICKSTART.md |
| Share a complete head or selective semantic piece | docs/SEMANTIC_CAPSULES.md |
| Understand operational authority and corpus lifecycle | docs/OPERATIONAL_PHILOSOPHY.md |
| Do conceptually or meaning-sensitive work with PGX | docs/CONSTRUAL_ENGINEERING.md |
| Author or interpret traversal expressions | docs/README.md and the linked 4C guides |
| Inspect request, response, and tool guarantees | LLM_TOOL_CONTRACT.md and TOOL_CATALOG.json |
| Validate and release a corpus directory | docs/CORPUS_OPERATIONS.md |
| Preserve a Parmesan 3 or earlier workspace for PM4+ | docs/MIGRATING_TO_PARMESAN_4.md |
| Verify a software release | RELEASE.md, RELEASE.json, PACKAGE_MANIFEST.json, and SHA256SUMS.txt |
| Make a small change or prepare a release | CONTRIBUTING.md |
| Inspect an annotated external corpus materialization | corpus-artifacts/README.md |
Small changes use short-lived, purpose-named branches such as docs/..., fix/..., feature/..., and chore/.... Open a pull request into main, inspect the complete diff, and merge the coherent change. A branch prefix is a naming convention, not a permanent category branch.
Ordinary merged changes accumulate as unreleased work. GitHub Releases and version tags are periodic, immutable release cuts—not a required consequence of every documentation or source change. See CONTRIBUTING.md for the full workflow.
Parmesan is source-available, not open source. It is licensed under the PolyForm Noncommercial License 1.0.0. That license permits noncommercial use, modification, and sharing, including personal study and qualifying educational, nonprofit, public-research, public-safety, environmental, and government uses.
Commercial use requires a separate written agreement. To inquire, open a
GitHub Issue titled Commercial licensing inquiry and do not post
confidential information there.
The canonical downloadable artifacts are published in GitHub Releases. A normal release is one ZIP named PARMESAN_vMAJOR_MINOR_PATCH.zip; its immutable release UUID and final SHA-256 identify the exact delivered artifact.
Installing the bundled wheel is optional:
python -m pip install dist/parmesan-<version>-py3-none-any.whl
parmesan doctor