particles¶
Particles SDK: epistemic knowledge management for AI agents (v0.3 Core).
Usage:
Options:
-V, --version: Show the client version (and, in remote mode, the engine version) and exit.--install-completion: Install completion for the current shell.--show-completion: Show completion for the current shell, to copy it or customize the installation.--help: Show this message and exit.
Commands:
db: Manage the database.deposit: Deposit a file, URL, or literal text into...extract: Extract particles from a corpus entry, or...query: Query the particle store with a natural...lint: Run lint checks over the particle store.review: List or resolve INCONSISTENCY particles.reindex: Re-extract particles for stale or failed...reconcile: Demote superseded claims across corpus...quality: Show the extraction quality dashboard.export: Export the knowledge base to an external...project: Render (or drift-check) a documentation...audit: Audit an agent-memory directory: harvest,...structure: Annotate particles with a structured...modality: Reclassify claims whose adjudicability...subjects: Manage subjects (canonical real-world...benchmark: Whole-pipeline system benchmarks (ADR...config: Inspect and validate Particles...conformance: Conformance Profile checks, the...corpus: Inspect deposited corpus entries.curate: Review the curation queue: today's...engine: Remote engine server.events: Inspect the operator event log.extractor: Manage extractor registry (Extension A).hook: Machine-facing Claude Code lifecycle hooks...import: Bulk-onboard existing knowledge bases...inbox: Process URLs queued from an iOS Shortcut...init: Install (or remove) an agent-harness...interchange: Export / import portable store bundles...links: Manage typed relations between particles...mcp: Model Context Protocol server (read-only,...memory: Agent-memory maintenance (ADR...particle: Inspect individual extracted particles.rules: Operating-rule source documents tracked by...skills: Install the agent-onboarding skill files...synthesis-cache: Inspect and prune the shared...trust: Manage source trust rules.vocab: Vocabulary documents: a store's reviewed...
particles db¶
Manage the database.
Usage:
Arguments:
action: Action: init [required]
Options:
--force: init: drop every particle-store table (preserving the corpus, the blob store and the session-exposure record) and rebuild from scratch. this is the upgrade path across a SCHEMA_VERSION major bump. Confirms before dropping.--help: Show this message and exit.
particles deposit¶
Deposit a file, URL, or literal text into the corpus.
Usage:
Arguments:
source: File path or URL to deposit. Pass '-' to read the content from stdin. Omit it when using --text.
Options:
--text <str>: Deposit a literal string instead of a file or URL. This is the CLI half of the MCPdeposit_texttool, so you no longer have to write a temp file to record one note. Mutually exclusive with a source argument.particles deposit -reads the same content from stdin. Defaults to source-type CONVERSATION; attributed to --deposited-by on both the deposited_by and author_id axes.--deposited-by <str>: Agent or operator ID [default: operator]--source-type <str>: Override the source_type (normally auto-detected from the extension / URL / content; you rarely need this). Core values (particles.core.schema.SourceType): WEB_PAGE, PDF, CSV, CONVERSATION, DATA_EXPORT, LOCAL_FILE, LOCAL_MARKDOWN, ACADEMIC_PAPER, FORUM, BLOG, TAXONOMY_DEFINITION, TRUST_LENS_DEFINITION, VOCABULARY_DOCUMENT. Domain extractors register their own, e.g. JOURNAL, REDDIT_POST, HACKERNEWS_THREAD, MASTODON_THREAD, GITHUB_REPO / GITHUB_GIST / GITHUB_PAGES, WIKIDATA_API, NUMISTA_API_COIN / NUMISTA_API_ISSUER, NOMISMA_API. Use --journal for the JOURNAL shortcut.--journal: Mark this deposit as a personal JOURNAL so the journal-aware extractor handles it (reifies feelings/opinions and emits the NARRATIVE graph). Shorthand for --source-type JOURNAL; an explicit --source-type wins.--tags <str>: Comma-separated tags--date <str>: Record this content's authorship date as content_published_at (ISO YYYY-MM-DD). Overrides the leading-date and file-mtime auto-detection. Local-file deposits only; ignored with a warning for URLs.--split-by-date: Split a multi-entry local file at standalone date-line boundaries into N corpus entries, each with its own content_published_at (a journal / changelog / daily-log that concatenates many dated entries). Opt-in; default off leaves today's one-file-one-entry behaviour unchanged. Local files only; mutually exclusive with --date. A file that is not actually multi-entry deposits as a single entry.--follow-post-links / --no-follow-post-links: Follow the post's primary URL for link-shaped sources (Reddit / HN / Mastodon link cards). When unspecified, the extractor's default applies: Reddit / HN / Mastodon default to True, everything else to False.--follow-comment-links / --no-follow-comment-links: Reserved-but-deferred. Passing --follow-comment-links emits a warning and proceeds as if False. Comment-link following is captured § Deferred and will land in a follow-up release.--mutability <str>: Mutability class: STABLE | MUTABLE | APPEND_ONLY | EPHEMERAL. Local files default to STABLE. MUTABLE means a new snapshot retires the generation of beliefs it replaces, the right class for a rule file like AGENTS.md that is edited in place. Local deposits only.--fetch-policy <str>: Re-fetch policy: LAZY | NEVER. Local files default to NEVER (frozen at deposit). LAZY opts the file into the refresh ladder, soparticles corpus refreshand the nightly consolidation pass re-check it against disk. Pair with --mutability MUTABLE. Local deposits only.-v, --verbose: Show importer + fetch INFO logs--debug: Show URL parsing, request URLs, auth state, and DEBUG logs--help: Show this message and exit.
particles extract¶
Extract particles from a corpus entry, or all PENDING entries at once.
Usage:
Arguments:
entry_id: Corpus entry ID (omit with --all-pending)
Options:
--snapshot-id <str>: Snapshot ID; defaults to latest PENDING--agent-id <str>: Asserted-by agent ID [default: cli-user]--all-pending: Extract all PENDING snapshots in deposit order--tag <str>: With --all-pending, extract only snapshots of corpus entries that carry this tag (for example memory-file for Claude Code memory files).-v, --verbose: Show quality notes and INFO logs--debug: Show raw LLM prompt/response and DEBUG logs-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
particles query¶
Query the particle store with a natural language question.
Usage:
Arguments:
question: Natural language question. Omit it with structural claim flags for the deterministic (no-LLM) modes.
Options:
--min-confidence <float>: Minimum confidence threshold [default: 0.0]--audience <str>: GENERAL, EXPERT, or REGULATORY [default: GENERAL]--top-k <int>: Number of particles to retrieve [default: 40]--subject <str>: Filter to particles about this subject ID--tag <str>: Filter by taxonomy tag (subtree-expanded; repeatable)--include-ancestors: Match particles tagged with a broader ancestor of each --tag as well (up-expansion over taxonomy parent links)--show-particles: Print retrieved particles with scores before the answer--show-source: After the answer, print the source passage behind each of the top hits, labelled exact (hash-verified chunk), located (best term overlap; not verified), or whole source. Display only: never affects ranking.particles particle source <id>does the same for one belief.--contestedness: Show per-result contestedness: the max−min spread of effective confidence across your policy set (local + adopted lenses). Absent when fewer than two policies are configured.--include-document-meta: Include DOCUMENT_META particles (claims about a source's own structure)--include-non-asserted: Include non-asserted particles: a document's rejected / superseded / deferred / counterfactual prose (polarity DECLINED / HYPOTHETICAL)--assertion-modality <str>: Filter to one modality: FALSIFIABLE, EVALUATIVE, EXPERIENTIAL, or CONSTITUTIVE. Omit to return every modality.--store <str>: Federate the query across these store handles (repeatable). Omit to query the default store. The first handle is the viewer whose trust policy ranks the merged results.--predicate <str>: Filter to claims whose predicate term equals this string (case-insensitive, exact: a CURIE and its expanded IRI are different strings; discover terms with --predicates).--object-eq <str>: Filter to claims whose object equals this value (typed when both sides normalize, i.e. numbers and ISO dates; else case-insensitive text).--object-gt <str>: Filter to claims whose object is greater than this number or ISO date. Claims whose object would not normalize are excluded and the exclusion count disclosed.--object-lt <str>: Filter to claims whose object is less than this number or ISO date (same normalization and disclosure as --object-gt).--object-contains <str>: Filter to claims whose object contains this substring (case-insensitive; works on every term kind).--count: Deterministic aggregate: the number of matching claims with their effective-confidence distribution. No question, no LLM call.--group-by <str>: Deterministic aggregate: bucket matching claims by 'subject', 'predicate', or 'object' with per-bucket counts and confidence distribution. No question, no LLM call.--min-effective-confidence <float>: Explicit confidence floor for the aggregate modes; excluded rows are disclosed. There is no default floor.--predicates: List the distinct predicate terms with kind and claim count: the vocabulary the exact-string --predicate filter matches against.--vocabulary: Report the store's vocabulary: each canonical predicate with its surface forms, claim count, object value shapes, the subject classes it attaches to, and its alignment, under a header of subject alignment and class counts and confirmed modelling decisions. Computed at read time, never stored. No question, no LLM call.--format <str>: Output format for --vocabulary: 'table' (default) or 'json'. [default: table]--grounded / --ungrounded: Grounded answer: every sentence cites the retrieved particle ids it rests on, and a sentence the model added is labelled [inference] (drawn over cited claims) or [background] (from nothing in the store). Cited ids are checked against the retrieved set and nothing is dropped. Default: query.grounded_answers.--as-of <str>: Answer as of this past instant (ISO-8601; a bare date means the start of that day, UTC): what did the store believe at T, and why did it stop believing it? Retired hits carry their supersession crossing; retirements the store cannot date are excluded with a disclosure line. A future instant is rejected.--help: Show this message and exit.
particles lint¶
Run lint checks over the particle store.
Usage:
Options:
--fix / --no-fix: Apply auto-fixable status transitions (STALENESS, RETRACTION_CASCADE, CORPUS_LINK_INTEGRITY). [default: no-fix]--semantic / --no-semantic: Run LLM-assisted semantic checks (slower) [default: no-semantic]--output-format <str>: Output format: markdown or json [default: markdown]-v, --verbose: Show all findings in full--category <str>: Restrict --verbose output to one finding_type (e.g. STALENESS, GRANULARITY_VIOLATION_CANDIDATE)--limit-per-category <int>: Cap verbose findings per category to keep output manageable; remainder is summarised. 0 disables the cap. [default: 50]--low-coverage-threshold <int>: Subjects with fewer ACTIVE CLAIM particles are flagged [default: 3]--help: Show this message and exit.
particles review¶
List or resolve INCONSISTENCY particles.
# List all pending conflicts
particles review
# Resolve a specific conflict
particles review PARTICLE_ID --action PREFER_A
# Neither side is worth keeping: retract both, no trust verdict
particles review PARTICLE_ID --action DISCARD --note "session state"
# Resolve all pending conflicts with one action
particles review --bulk BOTH_VALID
particles review --bulk PREFER_B # prefer newer/structured source
particles review --bulk BOTH_VALID --dry-run # preview without committing
particles review --bulk DISCARD --dry-run # list what would be retracted
A --bulk DISCARD lists every conflict with both sides and asks before it retracts anything (skip the prompt with --yes). Retraction has no undo.
Usage:
Arguments:
particle_id: INCONSISTENCY particle ID; omit to list
Options:
--action <str>: PREFER_A, PREFER_B, BOTH_VALID, DEFER, DISCARD--bulk <str>: Apply action to ALL pending conflicts--dry-run: Preview bulk action without committing-y, --yes: Skip the confirmation a --bulk DISCARD asks for--reviewer-id <str>: Reviewer identity [default: cli-user]--domain <str>: Domain for trust statement [default: general]--note <str>: Optional reviewer note--help: Show this message and exit.
particles reindex¶
Re-extract particles for stale or failed corpus entries.
With --estimate, measure on a sample what an --extractor-version reindex would change and cost, and stop there. Exit codes for --estimate: 0 when the estimate ran, 2 when it did not start (invalid options, the spend declined, or no --yes in a non-interactive run).
Usage:
Options:
--entry-ids <str>: Comma-separated entry IDs (full or unambiguous prefix); omit for auto. Combines with --extractor-version / --extractor-id / --provider-model by intersection: only the named entries that also match the filter are reindexed, and any that don't are reported.--extractor-version <str>: Old extractor version to replace--extractor-id <str>: Extractor name (e.g. github-repo-extractor): re-extract all of its particles regardless of version. Useful when a shared upstream change (e.g. a prompt revision in general.py) affects delegating extractors.--provider-model <str>: ": " pairing (e.g. openai:gpt-5.6-luna): re-extract every particle that pairing produced. The handle for undoing an uncalibrated provider swap. Matched exactly, and the scope unit is the snapshot, so a snapshot with a model-mixed population is re-extracted whole. Particles with no recorded pairing never match. --no-failed / --no-no-failed: Skip FAILED snapshot entries. Applies to auto-discovery only; --entry-ids resolves each entry to its latest COMPLETE snapshot. [default: no-no-failed]--dry-run: Print the work plan (entries / snapshots / particles in scope, with per-snapshot counts and any known-missing blobs) and exit without extracting: zero LLM calls, zero writes.--estimate: Measure what an --extractor-version reindex would change before running it: re-extract a seeded sample of the snapshots it would sweep, judge each sample's new claims against its stored ones, and report the projected share of changed snapshots and the projected cost of the full sweep. Spends only on the sample and writes nothing. Prints the plan and asks before spending; a non-interactive run needs --yes. Local store only.--yes: With --estimate: spend on the sample without asking.--sample-size <int range>: With --estimate: snapshots to sample (default: reindex.estimate_sample_size). [x>=1]--seed <int>: With --estimate: the sample's random seed (default: reindex.estimate_seed).--only-changed-components: Narrow an --extractor-version scope to the snapshots whose recorded extraction components changed. Not enabled yet: refused until an extractor version bump has run over a store whose snapshots record their components.--format <human|json>: Output format: a short human summary (default), or the full JSON result envelope including the per-snapshot plan. [default: human]-v, --verbose: Print scope size and per-entry progress while reindexing.--help: Show this message and exit.
particles reconcile¶
Demote superseded claims across corpus entries (supersession sweeps).
Usage:
Options:
--updates: Run the same-subject update sweep instead of the document-supersession sweep: retire a value when a later claim from the same source lineage gives a new value for the same attribute.--dependents: Run the re-anchor pass: restate claims that relied on a state an update retired, such as a place described as near the user's old flat. Resumes from the nightly cycle's position without moving it.--scope <str>: With --dependents: 'cursor' examines update retirements after the nightly position; 'store' examines every one. [default: cursor]--dry-run: Report what would be demoted without mutating the store.-v, --verbose: Print scope size and per-demotion progress.-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
particles quality¶
Show the extraction quality dashboard.
Displays calibration source distribution, corpus snapshot status, subject coverage metrics, recorded LLM spend, and the curation queue's precision over the default window. No LLM calls, just an instant read from the DB. For full structural and semantic diagnostics use: particles lint
Usage:
Options:
--help: Show this message and exit.
particles export¶
Export the knowledge base to an external format.
Available formats: obsidian, anki, wiki, logseq, jsonl, notion, graph.
particles export obsidian ./my-vault
particles export obsidian ./my-vault --min-particles=1 --min-links=2
particles export obsidian ~/Vault/Particles # a folder of its own
particles export obsidian ~/Vault --force # beside your own notes
particles export anki ./deck.txt --deck-name="Numismatics" --min-particle-confidence=0.7
particles export wiki ./my-wiki # incremental
particles export wiki ./my-wiki --dry-run # cost estimate
particles export wiki ./my-wiki --regenerate-all # bypass cache
particles export wiki ./my-wiki --without-synthesis # deterministic, no LLM
particles export wiki ./my-wiki --subjects "Pfennig,GDR"
particles export logseq ./my-graph # pages/ + bullet outline
particles export logseq ./my-graph --with-synthesis
particles export notion --dry-run # plan, zero API writes
particles export notion --database-id=abc123… # sync into a Notion DB
particles export notion --no-update-blocks # create-only (keep hand-edits)
particles export graph out.html --subject <id> # one Subject's neighbourhood
particles export graph out.html --query "why X?" # one query's retrieval set
particles export graph out.html --subject <id> --history --as-of 2006-08-24
The notion exporter is an API target: it takes NO output path and requires the NOTION_API_KEY environment variable (mint an internal integration at https://www.notion.so/my-integrations and share the target database with it). Run with --dry-run first to see the plan without writing.
Usage:
Arguments:
format: Export format: obsidian | anki | wiki | logseq | jsonl | notion | graph [required]output: Output path (directory for obsidian / wiki / logseq, file for anki / jsonl / graph). Optional for obsidian whenobsidian.default_output_pathis set in config.yaml; required for the filesystem exporters. The notion exporter is an API target and takes NO output path.
Options:
--min-particles <int>: Obsidian/Wiki/Logseq: minimum particle count per subject (0 = all; wiki default 3)--min-links <int>: Obsidian/Logseq: minimum graph link count per subject (0 = all)--deck-name <str>: Anki: root deck name prefix [default: Particles]--min-particle-confidence <float>: Cross-exporter: drop particles with effective_confidence below this threshold before any per-exporter downstream step. Overrides config.exporter_common.min_particle_confidence.--regenerate-all: Wiki: bypass the per-subject input-hash cache and rewrite every article--invalidate-stale-links: Wiki/Obsidian/Logseq: scan cached article bodies for [[X]] wikilinks; invalidate any article whose wikilinked subjects' canonical names have drifted since render. Cheaper than --regenerate-all when only a few subjects renamed.--subjects <str>: Wiki: comma-separated canonical subject names to limit the export to--dry-run: Wiki: report cache hits + regen count + token estimate without writing or calling the LLM--with-synthesis: Obsidian/Logseq: splice LLM-synthesised prose articles into per-subject notes. Requires ANTHROPIC_API_KEY. Shares the synthesis cache with the wiki exporter, so running multiple synthesising exporters pays LLM cost once per subject.--without-synthesis: Wiki: render every article as the deterministic structured listing: no LLM call, no ANTHROPIC_API_KEY, reproducible output. Bypasses the synthesis cache so existing LLM articles are replaced.--force: Obsidian/Logseq: export into a directory that holds Markdown files this export did not write, such as an existing vault, and overwrite any such file whose path a note takes. Without it the first export into a populated directory is refused, and a later one skips those paths. Files the export did not write are never deleted.--include-non-asserted: Include non-asserted particles: a document's rejected / superseded / deferred / counterfactual prose (polarity DECLINED / HYPOTHETICAL). Excluded from the rendered surface by default; the round-trippableinterchangeexport always keeps them.--subject <str>: Graph: render one Subject's neighbourhood, given as a subject id or an exact (case-insensitive) canonical name / alias. Scope is mandatory for the graph exporter: pass exactly one of --subject or --query; a whole-store render does not exist.--query <str>: Graph: render one query's retrieval set, the picture of the knowledge a query consults (top graph.query_top_k hits + their subjects). Mutually exclusive with --subject.--inconsistency <str>: Graph: render one contradiction's evidence: the INCONSISTENCY particle (full id or unique prefix) as the anchor, its two disputant beliefs with their true statuses, their subjects and sources. Mutually exclusive with the other scopes.--manifest <str>: Graph: with --section, render a projection manifest section's deterministic selection.--section <str>: Graph: the manifest section's region id or exact title (with --manifest).--hops <int>: Graph: neighbourhood radius for --subject scope (clamped to graph.max_hops) [default: 1]--history: Graph: include retired supersession-chain ancestors as ghosts (dashed, with the successor chain in the panel); the page gets a client-side history toggle--as-of <str>: Graph: render the graph as believed at this ISO-8601 instant (single-instant lens; undatable retirements are excluded fail-closed and disclosed). Two exports at two instants make the static belief-history demo.--max-nodes <int>: Graph: per-run node cap (clamped to graph.max_nodes; truncation is disclosed)--database-id <str>: Notion: the target database id to sync subjects into for this run (overrides config.notion.database_id). Share that database with your integration first. The NOTION_API_KEY token is read from the environment, never passed as a flag.--no-update-blocks: Notion: create-only. Write a page's particle blocks once and never rewrite the managed block range on re-sync, preserving hand-edits. Default behaviour owns the managed range and overwrites it so re-sync is idempotent.--help: Show this message and exit.
particles project¶
Render (or drift-check) a documentation projection.
particles project docs/projection/readme.yaml README.md
particles project docs/projection/readme.yaml --without-synthesis
particles project docs/projection/readme.yaml --check # CI drift gate
# Splice every declared region of the README in one pass:
particles project docs/projection/readme.yaml --splice-all
# Re-roll a single sentinel region:
particles project docs/projection/readme.yaml README.md --splice what-is
# Refresh the committed drift-gate bundle:
particles project docs/projection/readme.yaml --export-corpus
Usage:
Arguments:
MANIFEST: Path to a projection manifest (e.g. docs/projection/readme.yaml). [required]output: Output Markdown path. Optional when the manifest setsoutput:.
Options:
--without-synthesis: Render the deterministic structured listing: no LLM call, no ANTHROPIC_API_KEY, reproducible output. The drift gate uses this mode.--check: Drift gate: regenerate the deterministic snapshot and exit non-zero if it differs from the committed<name>.snapshot.md. Selection + structure are gated; LLM prose drift is advisory. No API key required.--splice REGION: Block-splice mode: write the rendered body between the<!-- BEGIN/END PROJECTED: REGION -->sentinels in the existing output file, preserving everything outside them, instead of overwriting the whole file. The output file must already carry the sentinel pair for REGION. On a manifest with per-sectionregion:bindings, renders only that region's section, the single-region re-roll path.--splice-all: Multi-region block-splice: render every section that declares aregion:and splice each body into its own sentinel pair in the output file, in one pass. Every derived section must declare a region.--export-corpus: Write the manifest's sibling<name>.corpus.jsonlgate bundle: exactly the particles the manifest's deterministic selection requires, encoded as interchange units the drift gate's ephemeral restore consumes. No render is performed.--verbose: Per-section progress logging.--help: Show this message and exit.
particles audit¶
Audit an agent-memory directory: harvest, extract, and report the rot census.
The line under the header says how many files extracted in full, how many were cut short at the output-token limit, and how many produced nothing, naming the last.
Exit codes: 0 means the audit completed. 1 means the report was written but the audit is incomplete: a harvested file produced no beliefs because its extraction failed (it stays pending, and re-running the same command retries it), or the contradiction check was skipped (no API key, or the LLM became unavailable, for example an exhausted credit balance). The findings in the report still stand. 2 means the audit did not start (invalid options, no API key for a harvest, a missing path, nothing to audit, or the cost confirmation was declined).
Usage:
Arguments:
path: Memory directory (or single file) to harvest + audit. Omit to re-audit the existing store without harvesting.
Options:
--transcripts <path>: Opt-in: also harvest session transcripts (*.jsonl) from DIR, newest first, capped at audit.transcript_max_entries (--max-entries overrides).--max-entries <int>: Cap harvested entries (default: audit.transcript_max_entries for transcripts; unlimited for memory files).--estimate: Print the cost estimate (calls, tokens, a dollar range at the configured model's list price, and the expected wall time) and exit: no deposit, no LLM call. With --format json the estimate is printed as JSON.--yes: Skip the cost-confirmation prompt.--judge: LLM-judge duplicate pairs (verified duplicates) instead of REPORT-mode candidates.--scope <str>: Semantic-finding scope (contradiction probe + duplicate scan): 'harvested' (default with PATH; headline counts only pairs touching this harvest's beliefs; the store-wide duplicate total is still disclosed) or 'store' (the whole store; the re-audit default).--output <path>: Write the Markdown report to FILE as well.--format <str>: Terminal format: markdown (default) or json. [default: markdown]--store <str>: Audit a named store (default: the default store). [default: default]-v, --verbose--debug--help: Show this message and exit.
particles structure¶
Annotate particles with a structured (subject-predicate-object) claim.
The annotation is derived from content and is never an assertion: this
verb cannot change a claim, its confidence, or its provenance. Particles
extracted since landed are annotated at extraction time for free;
this pass is for the ones that predate it, and it pays one LLM call each,
hence the rate limit and the resumable batch cap.
Particles whose prose has no honest triple are skipped, permanently and without complaint. Absence of an annotation is a legal state.
Usage:
Options:
--limit <int>: Max particles to annotate this run (default: structured_claim.backfill_batch_limit). Use 0 for the whole backlog in one run; that is safe, because the pass commits as it goes.--rate-limit-per-minute <int>: Max structurizer calls per minute (default: structured_claim.backfill_rate_limit_per_minute); 0 disables the delay.--structurizer-version <str>: Regenerate annotations stamped with a version OTHER than this one, instead of annotating unannotated particles (mirrorsreindex --extractor-version).--dry-run: Report the whole backlog (not the batch cap), the runs it implies, and current coverage; write nothing.-v, --verbose: Print per-particle progress.--debug: Debug logging.--help: Show this message and exit.
particles modality¶
Reclassify claims whose adjudicability default came from an outdated rule.
Each claim's assertion_modality is stamped with the classifier rule that
set it. When that rule has since changed, the stamp is stale, and particles
lint reports it as MODALITY_CLASSIFIER_STALE. This verb runs today's rule
over each stale claim, one LLM call each, and rewrites the value and its
stamp. It never changes a claim's content, confidence, or provenance.
It never makes a claim adjudicable on its own: a verdict that would flip a
claim to FALSIFIABLE is queued instead, and particles lint lists it as
MODALITY_GRANT_PENDING for particles particle reclassify. Verdicts that
withdraw adjudication, or confirm the stored value, are written. An
operator verdict is never overwritten, even one recorded during the run.
Journal-extractor claims are skipped, because the general rule would
replace the journal prompt's better-informed verdict; re-extraction
reclassifies them. A reply with no valid verdict leaves the claim as it
was. A claim whose value changed is re-paired by the next particles
memory consolidate run, under its new default.
Usage:
Options:
--limit <int>: Max claims to reclassify this run (default: modality_regeneration.batch_limit). Use 0 for the whole backlog in one run; that is safe, because the pass commits as it goes.--rate-limit-per-minute <int>: Max classifier calls per minute (default: modality_regeneration.rate_limit_per_minute); 0 disables the delay.--include-unclassified: Include claims no classifier ever ran on: claims extracted with classification off, claims from structured extractors, and direct assertions.--dry-run: Report the whole backlog and the stamp census by state and classifier; write nothing.-v, --verbose: Print per-claim progress.--debug: Debug logging.--help: Show this message and exit.
particles subjects¶
Manage subjects (canonical real-world entities).
particles subjects list [--order name|degree] [--phantoms-only]
particles subjects search QUERY
particles subjects show ID
particles subjects alias ID NAME [NAME ...]
particles subjects confirm SUBJECT_ID NAMESPACE:ID
particles subjects unlink SUBJECT_ID NAMESPACE:ID
particles subjects merge SOURCE_ID TARGET_ID [--dry-run]
particles subjects delete SUBJECT_ID [--force]
particles subjects gc [--dry-run] (alias: prune-empty)
particles subjects set-class SUBJECT_ID CLASS (e.g. nmo:NumismaticObject)
particles subjects split SOURCE_ID --particle PID [--particle PID ...] \
(--new-name "Applied Optoelectronics" | --new-external-id wikidata:Q30297735) \
[--dry-run]
particles subjects relink-gated [--tier N ...] [--sample N --seed S] [--apply]
Usage:
Arguments:
action: Action: list, search, show, alias, confirm, unlink, merge, split, delete, gc, set-class, fix-labels, find-duplicates, relink-gated [default: list]rest...: Arguments for the chosen action
Options:
--dry-run: Preview merge/split/gc without committing--force: delete only: remove a non-phantom subject (one with ACTIVE particles)--phantoms-only: list only: restrict to phantom subjects (zero ACTIVE particles)--order <str>: list only: 'name' (alphabetical) or 'degree' (most ACTIVE linked particles first) [default: name]-p, --particle <str>: Particle ID to split off from the source (split only; repeat for multiple)--new-name <str>: Approximate name for the new Subject (split only). Canonicalised via the resolver.--new-external-id <str>: Authoritative external identifier for the new Subject (split only), e.g. wikidata:Q30297735. Skips resolver search; pulls metadata directly.--apply: relink-gated only: write the links. Without it the run only reports.--tier <int>: relink-gated only: a recovery tier to use (1 record, 2 structured claim, 3 backticks). Repeat for several. Default: subject_gate.relink_tiers.--sample <int range>: relink-gated only: print this many planned relinks, for a precision check. [default: 0; x>=0]--seed <int>: relink-gated only: the seed that picks the --sample relinks. [default: 0]--help: Show this message and exit.
particles benchmark¶
Whole-pipeline system benchmarks, distinct from the per-extractor particles extractor benchmark* verbs.
Usage:
Options:
--help: Show this message and exit.
Commands:
observer: The two-project observer fixture, with...leakage: Measure how much of each query answer the...memory: The LongMemEval agent-memory benchmark...rot: The memory-rot benchmark.relevance-floor: The relevance-floor benchmark: how often...
particles benchmark observer¶
The two-project observer fixture, with zero LLM calls.
Two repositories' memory files, sharing generic subjects, evolve over
--days and are harvested into one scratch store through the real
pipeline with scripted extraction and a scripted contradiction probe.
Each day, every line a project currently states is checked through that
project's observer: in view, or not, and if not, which mechanism retired
it (cross-project supersession, the generation cascade, or a surviving
particle attested only by the other project) and whether the winner is in
view. Report-only; the only number the default flip is decided
against.
Usage:
Options:
--seed <int>: World seed; repeat for several worlds (default: 1–8).--days <int range>: Simulated days per world. [default: 14; x>=2]--output <path>: Write the report here.--format <str>: Output format: "markdown" (default) or "json". [default: markdown]--store-dir <path>: Keep the per-seed scratch stores under this directory.--arm <lines|chunked>: How extraction reaches the store:linesre-emits every line (duplicate suppression);chunkedsends two lines per chunk through carry-forward. [default: lines]--help: Show this message and exit.
particles benchmark leakage¶
Measure how much of each query answer the retrieved particles do not support.
Each question runs through the query operation as configured. Every sentence of its answer is then judged against the particles the answer was composed from, on the llm.benchmark model, which must differ from the composer's. The headline is the share of claim-bearing sentences judged unsupported. The run is LLM-priced and estimate-gated, and it never writes to the store.
Usage:
Options:
-q, --question <str>: Measure this question instead of the held-out set; repeat for several. Prints one row per question.--heldout <path>: Held-out JSONL frombenchmark relevance-floor harvest(default: benchmark_relevance_floor.heldout_path).--store <str>: Store handle to query (default: the default store).--top-k <int range>: Retrieval depth the answer is composed over (default: benchmark_leakage.top_k). [1<=x<=200]--limit <int range>: Measure a seeded sample of N questions, stratified by source. [x>=1]--estimate: Print the projection and exit before any LLM call.-y, --yes: Skip the confirmation above the call threshold.--per-question / --aggregate-only: One table row per question id (default: on with --question, off otherwise).-o, --output <path>: Write the rendered report to this path as well.--format <table|json>: table (default; no question, answer, or sentence text) or json (the report of record; carries that text). [default: table]--checkpoint <path>: Checkpoint file for a held-out run (default: beside the held-out set), so an interrupted run never re-pays a finished question.--allow-in-repo: Permit a --format json --output inside a git work tree.--grounded / --ungrounded: Measure grounded answers, where the composer cites particle ids per sentence and labels its own inference and background. Cited sentences are judged against the ids they cite, and the labels are reported beside the silent unsupported count. Default: query.grounded_answers.--help: Show this message and exit.
particles benchmark memory¶
The LongMemEval agent-memory benchmark. The bare verb runs it; rejudge re-scores a saved report under the current judge protocol.
Usage:
Options:
--limit <int range>: Questions to run (stratified by type under the pinned seed; default: benchmark_memory.default_question_limit) [x>=1]--all: Run every question in the variant (mutually exclusive with --limit)--variant <oracle|s|m>: LongMemEval variant: oracle | s | m (default: benchmark_memory.variant)--types <str>: Comma-separated question-type filter (e.g. 'multi-session,knowledge-update')--estimate: Print the projected LLM call count + token volume and exit: no LLM call.--yes: Skip the cost-confirmation prompt.--output <path>: Write the rendered report to FILE as well as stdout.--format <table|json>: Output format [default: table]--store-dir <path>: Directory for the per-question scratch stores (kept after the run; default: a deleted temp dir)--dataset-file <path>: Local LongMemEval-format JSON file (skips the pinned download; used by the checked-in fixture and pre-verified copies)--context-budget <int range>: QA-at-budget clamp: cap condition ii's particle context at ~N tokens (rank order; baselines unclamped). Recorded on the run tuple; compare only against a matching run. [x>=1]--top-k <int range>: Retrieval depth for condition i and the qa_particles context (default: benchmark_memory.top_k). Recorded on the run tuple; a top_k sweep is a sweep of this flag against one fixed store set. [x>=1]--qa / --no-qa: Run the end-to-end QA family (conditions ii-iv). --no-qa reports the retrieval stage alone and makes NO LLM call at all once the stores exist: the free tier for a retrieval-only ablation arm. The three QA rows then rendernot run. [default: qa]--consolidation: Ablation: run the dream cycle's pass list (reconcile, census, utility, abstraction) on each scratch store between extract and retrieve: the controlled instrument. LLM-priced (reconcile probes, contradiction probes); recorded on the run tuple. Mutually exclusive with --abstraction, which the cycle runs itself.--dedup-judge: Ablation: run the co-evidential LLM judge in APPLY mode on each scratch store before retrieval, linking PARAPHRASE pairs CO_EVIDENTIAL so the ranker collapses them inside top-k. LLM-priced (one judged cluster per Subject); recorded on the run tuple.--reuse-stores: Replay the scratch stores an earlier --store-dir run persisted instead of depositing and extracting again: zero write-time LLM calls. Requires --store-dir, and refuses unless that set's write-side tuple (dataset, selection, extraction + embedding model, write-time reconciliation knobs) matches this run's.--abstraction: Ablation: run the abstraction-promotion pass (auto mode, age gate 0) on each scratch store between extract and retrieve. Recorded on the run tuple.--concurrency <int range>: Run up to N questions at once (each owns its scratch store; the report is identical to a sequential run's). Practical ceiling is your API rate tier; past ~4-8 the extra parallelism becomes 429 retries, not speed. [default: 1; x>=1]--fresh: Discard this experiment's checkpoint and start over. Runs are checkpointed per completed question by default, so an interrupted run resumes (and a completed run replays free) when re-invoked with identical knobs.--pooled: Dispatch each question's haystack extractions as one pooled Message Batches job. This roughly halves the bill on a batch-eligible provider at the cost of latency (a batch's floor is one poll interval). Same model, prompt, and budget, so the report is comparable to an unpooled run's; degrades to sequential calls when llm.batch is off.--batch-qa: Submit the QA answer + judge calls (conditions ii-iv) as Message Batches jobs, one answer batch and one judge batch per condition, all at 50% price, instead of one sequential call per question. The sibling of --pooled for the answerer/judge (the two compose); same model/prompt/budget, so the report is comparable. Off by default (a batch's floor is one poll interval: the right trade for a paid run, the wrong one for a small/interactive run); degrades to sequential calls when llm.batch is off.--memory <particles|chunks|notes>: The memory under test: particles (the store; the default), or a COMPARATOR memory over the same questions, answer scaffold, judge and retrieval scoring: chunks (raw-transcript RAG, no write-time LLM call) or notes (LLM-written session notes by the extraction model). The report's selection.memory names which ran. [default: particles]--baselines / --no-baselines: Run the qa_full_context / qa_no_memory baseline conditions. --no-baselines is for a comparator run reusing the particles run's baseline columns (same tuple ⇒ same calls); they rendernot run. [default: baselines]--help: Show this message and exit.
Commands:
rejudge: Re-score a saved report's stored answers...
particles benchmark memory rejudge¶
Re-score a saved report's stored answers under the current judge.
Re-runs only the judge call (llm.benchmark, under the configured
benchmark_memory.judge_protocol) over each QA row's recorded answer;
no answer call is made, so the full-context baseline is not re-paid and
the answers being judged do not change. Rows with no stored answer stay
excluded, with the count disclosed. The output names the source report
and both judge tuples in its first quality note.
Usage:
Arguments:
report: A savedbenchmark memory --format jsonreport whose QA rows carry the answering model's replies (written by v1.141.1 or later). [required]
Options:
--output <path>: Write the re-judged report here as JSON: a complete report of record (retrieval stage copied, QA conditions re-scored, provenance in the first quality note), regardless of --format. [required]--format <table|json>: What to print on stdout: the table, or the JSON. [default: table]--dataset-file <path>: Local LongMemEval-format JSON file for the report's variant (default: the pinned download for the variant and revision the report records). The judge prompt needs each question's text and reference answer, which the report does not carry.--yes: Skip the cost-confirmation prompt.--help: Show this message and exit.
particles benchmark rot¶
The memory-rot benchmark. The bare verb runs it; rescore re-classifies a saved report under the current scorer.
Usage:
Options:
--arm <oracle|probe|live>: Perception arm: oracle (scripted extraction + scripted §6.6 probe; zero LLM calls, deterministic), probe (scripted extraction, live contradiction probe), or live (the general extractor, i.e. the product). [default: oracle]--seed <int>: World seed; repeat for several worlds (default: benchmark_rot.seeds).--days <int range>: Simulated world length (default: benchmark_rot.days). [x>=30]--top-k <int range>: Probe top-k (default: benchmark_rot.top_k). [x>=1]--trust-policy / --no-trust-policy: Write the domain rule demoting the untrusted source channel (the operator's policy). --no-trust-policy measures the neutral-when-silent default instead. [default: trust-policy]--estimate: Print the projected LLM calls and cost, then exit.-y, --yes: Skip the confirmation above the call threshold.-o, --output <path>: Write the rendered report to this path as well.--format <table|json>: table (default) or json (the report of record). [default: table]--store-dir <path>: Keep each world's scratch store (and its blobs) here for inspection.--cache-dir <path>: Persist the paid arms' extraction results here, so a re-run that changes only candidacy or the ladder pays probes alone. The key includes the extractor, the resolved model and the SDK version, so a prompt or model change is a miss, never a silent replay.--attribute <str>: Stamp this author id on every session, which is what a multi-store needs before the attribution rule lets an update supersede.--real-pairs / --no-real-pairs: On the probe and live arms, also score the live update checks against your demotion rulings from the curation queue (/demotion-rulings.jsonl), reported in a section of their own. Skipped when the file is absent. [default: real-pairs] --rulings <file>: Read demotion rulings from this file instead of the default one.--help: Show this message and exit.
Commands:
rescore: Re-classify a saved rot report under the...
particles benchmark rot rescore¶
Re-classify a saved rot report under the current scorer.
Free: retrieval is taken as recorded, with no store, encoder, or LLM call. The
output is a complete report of record with selection.scorer_version set
to what ran and a first note naming the source and both versions.
Usage:
Arguments:
report: A saved rot report (--format json output). [required]
Options:
-o, --output <path>: Where to write the re-scored report (JSON). [required]--format <table|json>: What to print: table (default) or json. [default: table]--help: Show this message and exit.
particles benchmark relevance-floor¶
The relevance-floor benchmark: how often the query gate refuses an answerable question, on real questions. harvest builds the private held-out set; the bare verb replays it (free) and, with --judge, scores it; resweep re-renders a saved report over any floor list.
Usage:
Options:
--heldout <path>: Held-out JSONL fromharvest(default: benchmark_relevance_floor.heldout_path).--store <str>: Store handle to replay against (default: the default store).--top-k <int range>: Retrieval depth (default: benchmark_relevance_floor.top_k). The floor reads the maximum cosine over the rendered top-k, so this is on the run tuple. [1<=x<=200]--limit <int range>: Replay a seeded sample of N questions, stratified by source. [x>=1]--judge: Run the LLM-priced stage too: answer every question with the gate disabled, then judge the answer grounded-and-useful. Estimate-gated.--estimate: With --judge: run the free replay, print the projection, and exit before any LLM call.-y, --yes: Skip the confirmation above the call threshold.-o, --output <path>: Write the rendered report to this path as well.--format <table|json>: table (default; aggregate-only, no question text) or json (the report of record; carries question and answer text). [default: table]--replay-from <file>: Reuse the free replay recorded in a saved JSON report instead of re-running it (the replay is free but slow on a large store). Refused unless top_k and the encoder match and it covers every question asked for.--checkpoint <path>: Judged-stage checkpoint file (default: beside the held-out set), so an interrupted run never re-pays a finished question.--allow-in-repo: Permit a --format json --output inside a git work tree.--help: Show this message and exit.
Commands:
harvest: Build the private held-out question set...resweep: Re-sweep a saved report over a floor list...
particles benchmark relevance-floor harvest¶
Build the private held-out question set from agent transcripts.
Pure parsing: no store, encoder, or LLM call. Secrets are redacted before a question is kept. Prints a census only, never a question.
Usage:
Options:
--transcripts <path>: Directory of agent transcripts (*.jsonl), searched recursively (default: benchmark_relevance_floor.transcripts_dir).-o, --output <path>: Held-out JSONL to write (default: benchmark_relevance_floor.heldout_path).--prompts / --no-prompts: Harvest question-shaped sentences the operator typed to the agent as well: a proxy source, reported apart. --no-prompts keeps explicit memory queries only. [default: prompts]--allow-in-repo: Permit an --output inside a git work tree.--help: Show this message and exit.
particles benchmark relevance-floor resweep¶
Re-sweep a saved report over a floor list and print the aggregate table.
Free: the cosines and labels are taken as recorded (no store, encoder, or LLM call). This is also how a private JSON report of record becomes the publishable table, which carries no question text.
Usage:
Arguments:
report: A saved report (--format json output). [required]
Options:
--floor <float>: A floor to evaluate; repeat for several (default: benchmark_relevance_floor.floors).--help: Show this message and exit.
particles config¶
Inspect and validate Particles configuration.
Usage:
Options:
--help: Show this message and exit.
Commands:
validate: Load and validate config.yaml (+ env...
particles config validate¶
Load and validate config.yaml (+ env overrides); report errors readably.
Resolves the same config the rest of the SDK would load, runs the Pydantic
validation, and prints a human-readable summary. Exits non-zero on the first
invalid field or an unparseable file, so it is safe to gate a deploy on
particles config validate.
Usage:
Options:
--help: Show this message and exit.
particles conformance¶
Conformance Profile checks, the behavioural ground truth.
Usage:
Options:
--help: Show this message and exit.
Commands:
check: Self-certify against the Conformance...show: Print the loaded Conformance Profile's...
particles conformance check¶
Self-certify against the Conformance Profile; exit 1 on any FAIL.
Usage:
Options:
--level <str>: Which level to check: L2, L3, or all (default). [default: all]--json: Emit the report as JSON instead of text.--help: Show this message and exit.
particles conformance show¶
Print the loaded Conformance Profile's version, constants, and formulas.
Usage:
Options:
--help: Show this message and exit.
particles corpus¶
Inspect deposited corpus entries.
Usage:
Options:
--help: Show this message and exit.
Commands:
list: List all deposited corpus entries.show: Show details, extracted particles, and...cat: Dump a snapshot's stored content: the...delete: Delete a corpus entry, its snapshots, and...retract: Retract every live particle from a source,...prune-orphans: Sweep dangling rows left by older deletes...refresh: Re-check deposited local sources against...fsck: Audit every blob the store references;...links: Inspect cross-entry follow edges.
particles corpus list¶
List all deposited corpus entries.
Usage:
Options:
--source-type <str>: Filter by source type (PDF, WEB_PAGE, WIKIDATA_API, …)--json: Emit machine-readable JSON with the full, untruncated fields (entry_id, source_type, uri_r, extraction_status, particle_count, tags, created_at) instead of the human table.--help: Show this message and exit.
particles corpus show¶
Show details, extracted particles, and follow edges for a corpus entry.
Usage:
Arguments:
entry_id: Entry ID (prefix OK) [required]
Options:
--limit <int>: Max particles to show [default: 10]--help: Show this message and exit.
particles corpus cat¶
Dump a snapshot's stored content: the exact bytes the extractor saw.
Accepts a snapshot ID or a corpus-entry ID (prefix OK); an entry resolves to
its most-recent snapshot. By default renders the same text the extractor
derives from the blob (html2text for HTML, pypdf for PDF), so an empty
preview explains an "Empty content" / zero-particle extraction. --raw
streams the original bytes (pipe to a file or less). Identifying
metadata (snapshot id, hash, byte size) is written to stderr, so stdout
stays pipeable.
Usage:
Arguments:
selector: Snapshot ID or corpus-entry ID (prefix OK; entry → latest snapshot) [required]
Options:
--raw: Write the raw stored bytes to stdout instead of the text preview.--help: Show this message and exit.
particles corpus delete¶
Delete a corpus entry, its snapshots, and the particles only it supports.
A particle that another entry also supports is kept, with this entry's source refs removed. When the removed ref was its earliest source, the next-earliest one becomes the age anchor. The delete is recorded as a CORPUS_ENTRY_DELETED event that holds the entry id and counts, not the deleted content.
Usage:
Arguments:
entry_id: Entry ID (prefix OK) [required]
Options:
-y, --yes: Skip confirmation prompt--help: Show this message and exit.
particles corpus retract¶
Retract every live particle from a source, preserving the corpus + snapshots.
The non-destructive sibling of corpus delete: live particles
(ACTIVE / INCONSISTENCY) become RETRACTED with reason SOURCE_RETRACTED; the
entry, its snapshots, and the particles themselves survive so the audit
trail is intact. Idempotent. Run particles lint afterwards to cascade
PROVENANCE_STALE to downstream particles.
Usage:
Arguments:
entry_id: Entry ID (prefix OK) [required]
Options:
--reason <str>: Operator rationale, recorded in the event log--dry-run: Show the plan without writing-y, --yes: Skip confirmation prompt--help: Show this message and exit.
particles corpus prune-orphans¶
Sweep dangling rows left by older deletes (orphan subjects, stale index rows).
Pre-fix corpus delete removed particles but not the index rows keyed
on them, so long-lived DBs accumulate particle_subjects /
particle_tag_edges / particle_relations rows pointing at deleted
particles, subjects with no remaining link, and synthesis_cache rows
keyed on vanished subjects. This one-off verb cleans all of them.
Usage:
Options:
-y, --yes: Skip confirmation prompt--help: Show this message and exit.
particles corpus refresh¶
Re-check deposited local sources against the files on disk.
Walks every LAZY entry with a file:// URI-R, comparing the file's
mtime and then its SHA-256 against the latest snapshot. A changed file gets
a new PENDING snapshot; particles extract --all-pending (or tonight's
consolidation run) turns that into current beliefs.
This is the on-demand form of consolidation pass 0.5; the scheduled cycle runs the same sweep nightly.
Usage:
Arguments:
entry_id: Refresh one entry (full id or unambiguous prefix). Omit to sweep all.
Options:
--force: Tier 3: re-check regardless of fetch_policy and the per-source-type re-fetch floor. The escape hatch for a content change that preserved the file's mtime.--backfill-cascade: Instead of re-checking sources, apply the generation cascade to MUTABLE entries whose snapshots already moved, demoting ACTIVE particles anchored to a superseded snapshot. Stores that predate the change carry a backlog of these; the forward-looking cascade only fires on newly-extracted snapshots.-y, --yes: Skip the confirmation prompt-v, --verbose: Verbose logging--help: Show this message and exit.
particles corpus fsck¶
Audit every blob the store references; optionally re-home the strays.
Read-only by default and exhaustive: the operator-invoked sibling of the
sampled probe config validate runs. Reports three disjoint counts:
present in the resolved blob dir, found elsewhere under a
--search root, and missing.
--re-home copies (never moves) the strays home, rejecting any candidate
whose recomputed SHA-256 does not match the name it was found under. The
database is never written: blobs that are genuinely gone are reported with
their entry IDs and URIs, and the choice between re-depositing from source
and retracting stays yours.
Exits non-zero while any referenced blob is still unreachable.
Usage:
Options:
--search <path>: Look for strays under this blob root too, the directory holding the two-character shards (repeatable). Nothing is inferred: the audit tells you what is missing so you can point --search at where you think it went.--re-home: Copy digest-verified strays found under --search into the blob dir.--dry-run: Report what --re-home would copy, without copying.--help: Show this message and exit.
particles corpus links¶
Inspect cross-entry follow edges.
Usage:
Options:
--help: Show this message and exit.
Commands:
list: List follow edges written by deposit-time...suggest: Suggest undeposited URLs the corpus...dismiss: Stop a URL from resurfacing in ``corpus...
particles corpus links list¶
List follow edges written by deposit-time URL following.
Without an entry-id, lists every edge in deposit-time order. With an
entry-id, shows the edges touching that entry (outgoing / incoming
per --direction). Operators use this to audit which Reddit / HN
/ Mastodon posts amplified which external sources.
Usage:
Arguments:
entry_id: Entry ID (prefix OK). Omit to list every follow edge.
Options:
--direction <str>: Filter when entry-id set: out (this→linked), in (others→this), both. [default: both]--help: Show this message and exit.
particles corpus links suggest¶
Suggest undeposited URLs the corpus frequently cites.
Ranks URLs mentioned across the corpus but not yet deposited, by
trust-weighted distinct-source diversity × recency. Suggestion-only:
nothing is fetched or crawled. Deposit one with particles deposit <url>;
silence one with particles corpus links dismiss <url>.
Usage:
Options:
--limit <int>: Max suggestions to show (default: config rank_cap).--min-sources <int>: Min distinct citing sources to surface (default: config).-o, --output-format <str>: table | json [default: table]--help: Show this message and exit.
particles corpus links dismiss¶
Stop a URL from resurfacing in corpus links suggest.
A permanent dismiss (the default) suppresses the URL indefinitely; --snooze
N suppresses it for N days. The action is audited in the operator event
log.
Usage:
Arguments:
url: URL to dismiss (canonicalized before matching). [required]
Options:
--snooze <int>: Snooze for N days instead of a permanent dismiss.--help: Show this message and exit.
particles curate¶
Review the curation queue: today's highest-leverage problems in the store.
Each card is one problem the existing checks found (an expired or contested
belief, a likely duplicate, an unsubjected claim, a frequently cited URL
that was never deposited). The listing shows the beliefs involved, the
question the card asks, and what each offered gesture would do. Resolve a
card with particles curate apply GESTURE KEY.
Gestures applied directly by curate apply:
affirm the belief is correct; hide the card for good
snooze hide the card for a while (--days N)
dismiss not a real problem; hide the card for good
retract the belief is wrong; retract it (--reason TEXT)
merge a duplicate pair is one claim; link it co-evidential
deposit deposit a frequently cited URL into the corpus
assign-subject attach an unsubjected belief (--subject ID-OR-NAME)
supersede replace the belief with a corrected one (--content TEXT
--reason TEXT --confidence F)
accept, reject decide on a proposed generalization
Gestures that name another command instead:
comment resolve an INCONSISTENCY with particles review
reindex re-extract failed snapshots with particles reindex
--precision reports how often the queue was right over a window, read
from the gesture log: per kind, the share of cards acted on, dismissed,
snoozed, and never touched, and what acted and dismissed mean for that
kind. The same block appears in particles quality.
Usage:
Options:
-n, --limit <int>: Cap the cards shown (default: curation.session_size).-k, --kind <str>: Restrict to one card kind: stale, retraction_cascade, broken_provenance, confidence_decay, recency_decay, contradiction, contested, no_subject, gated_subjects, duplicate_pair, uncited_url, failed_snapshots, proposed_abstraction, stale_basis, inconsistency, demotion.--semantic: Run the LLM-assisted finders (semantic contradiction).--refresh: Rebuild the card collection before showing it. Slow: the structural finders re-run store-wide. Contradiction cards carry forward from the last census unless --semantic re-probes them. Run this once on a store with no collection yet; the nightlymemory consolidatedoes it for you after that.--no-snapshot: Bypass the persisted collection entirely and run the finders for this invocation without caching the result.--precision: Instead of the queue, report how often it was right: per card kind, the cards acted on, dismissed, snoozed and never touched over a window, with the denominator. Read from the gesture log; nothing is stored. --kind narrows the table to one kind.--since <str>: With --precision: the start of the window, as YYYY-MM-DD or an ISO timestamp (default: curation.precision_window_days before now).--format <str>: With --precision: table (default) or json. [default: table]--verbose--debug--help: Show this message and exit.
Commands:
apply: Apply a gesture to a card from the...
particles curate apply¶
Apply a gesture to a card from the curation queue.
Copy KEY from the key: line of the card in particles curate, which also
says what each gesture offered on that card would do.
Examples:
particles curate apply affirm KEY
particles curate apply snooze KEY --days 30
particles curate apply retract KEY --reason "Superseded upstream"
particles curate apply assign-subject KEY --subject pre-commit
particles curate apply supersede KEY --content "The window is 30 days."
--reason "Changed in 1.140" --confidence 0.85
particles curate apply resolve KEY --action BOTH_VALID --note "Different runs"
Usage:
Arguments:
gesture: affirm | snooze | dismiss | retract | merge | deposit | assign-subject | supersede | accept | reject | resolve. The queue listing says what each one does to that card. [required]card_key: The card key shown in the queue listing. [required]
Options:
--reason <str>: Rationale, recorded on the audit event. Required for supersede, where it is also the new belief's source unless --source or --corpus-entry is given.--days <int>: Snooze window in days.--subject <str>: Subject id or name. assign-subject takes one. For supersede, repeat it to replace the belief's subjects; omit it to keep them.--content <str>: supersede: the corrected belief, one claim.--confidence <float range>: supersede: your confidence in the corrected belief, 0 to 1. The new belief is attributed to curation.operator_identity as HUMAN_REVIEW. [0.0<=x<=1.0]--source <str>: supersede: text to deposit as the corrected belief's source (default: the --reason text).--corpus-entry <str>: supersede: cite an existing corpus entry as the source instead.--action <str>: resolve: PREFER_A, PREFER_B, BOTH_VALID, DISCARD, or DEFER. The listing names the actions this conflict offers; DEFER records a note and leaves it open.--note <str>: resolve: a note recorded on the review.--help: Show this message and exit.
particles engine¶
Remote engine server.
Usage:
Options:
--help: Show this message and exit.
Commands:
serve: Run the FastAPI engine, binding HOST:PORT.
particles engine serve¶
Run the FastAPI engine, binding HOST:PORT.
Unifies the bind with the fail-closed gate: HOST sets
api.bind_host so a non-loopback bind without a real PARTICLES_API_KEY
is refused before the socket opens.
With --daemon (or daemon.enabled) the process also schedules its own
background work in the FastAPI lifespan, the rider on the
external-scheduler contract. Without it, this command behaves exactly as it
always has.
Usage:
Arguments:
HOST:PORT: Interface and port to bind, e.g. 0.0.0.0:8000 (LAN/Tailscale) or localhost:8000 (loopback-only dev). [required]
Options:
--daemon: Resident mode: also run the in-process consolidation tick and intake watchers, so no launchd/cron is needed alongside the engine. Overrides daemon.enabled; configure the rest underdaemon.--help: Show this message and exit.
particles events¶
Inspect the operator event log.
Usage:
Options:
--help: Show this message and exit.
Commands:
list: List operator events, newest first.show: Show one operator event in full (header +...
particles events list¶
List operator events, newest first.
Usage:
Options:
--particle <str>: Only events touching this particle id--subject <str>: Only events touching this subject id--entry <str>: Only events touching this corpus entry id--type <str>: Only events of this type (e.g. SOURCE_RETRACTED)--limit <int>: Maximum events to show [default: 50]--help: Show this message and exit.
particles events show¶
Show one operator event in full (header + refs + payload).
Usage:
Arguments:
event_id: Event ID [required]
Options:
--help: Show this message and exit.
particles extractor¶
Manage extractor registry (Extension A).
Usage:
Options:
--help: Show this message and exit.
Commands:
conform: Run an extractor against the conformance...generate-fixture: Turn a deposited corpus entry into a...list: List all registered extractors with...trust-set: Override the trust weight for an extractor.benchmark: Run extraction-quality benchmarks against...benchmark-modality: Measure assertion_modality classification...benchmark-polarity: Measure claim-polarity classification...benchmark-validity: Measure event-anchored-validity quality...benchmark-compare: Compare two or more extractors against the...calibrate: Fit a temperature-scaling calibration for...calibrations: List stored calibrations per (provider,...calibration-forget: Retire one stored calibration record (ADR...
particles extractor conform¶
Run an extractor against the conformance fixture corpus.
Scores the fixtures the production registry routes to this extractor.
--all-accepted widens the run to every fixture the
extractor would take if handed it (for the fallback that is the
whole corpus), so the result is a deliberate probe, not the extractor's
conformance score, and it never updates the stored conformance verdict.
Phase 1 (current): report-only, in that no merge or registration is gated
on the result. The exit code still reflects it: under the default
--fail-on error, exit code 1 means the contract failed (a REQUIRED field
short of 100%, including every REQUIRED field when no fixture is scored,
or a FAIL-severity diversity rule violated on a REQUIRED field);
--fail-on warn additionally treats RECOMMENDED warnings as fatal. An
ADVISORY diversity finding (uncertainty_nature is the one
shipped today) is reported and never affects the exit code.
Usage:
Arguments:
extractor_id: EXTRACTOR_ID of a registered extractor [required]
Options:
--fixtures <path>: Override fixture directory (default: tests/conformance/fixtures)--recommended-threshold <float range>: Minimum populate-rate for RECOMMENDED fields (0.0–1.0) [default: 0.8; 0.0<=x<=1.0]--format <table|json>: Output format [default: table]--fail-on <error|warn>: Exit non-zero on errors only (default) or on warnings as well [default: error]--all-accepted: Score every fixture the extractor accepts(), not just the ones the registry routes to it. Report-only: never stores the verdict--help: Show this message and exit.
particles extractor generate-fixture¶
Turn a deposited corpus entry into a conformance fixture skeleton.
Reads the entry's latest stored snapshot + raw blob and writes
manifest.yaml + content.bin + snapshot.json under
<output-dir>/<fixture-id>, registering it in MANIFEST.yaml.
expected_acceptors is left empty for you to fill after verifying which
extractors the fixture should exercise.
Usage:
Arguments:
entry_id: Corpus entry ID (prefix OK) [required]
Options:
--id <str>: Fixture id (default: a slug of the entry URI + id prefix)--source-type <str>: Override the entry's source type--output-dir <path>: Fixture corpus directory (default: tests/conformance/fixtures) [default: tests/conformance/fixtures]--force: Overwrite an existing fixture directory--help: Show this message and exit.
particles extractor list¶
List all registered extractors with version, trust weight, and domain coverage.
Usage:
Options:
--help: Show this message and exit.
particles extractor trust-set¶
Override the trust weight for an extractor.
Usage:
Arguments:
extractor_id: Extractor ID [required]weight: New trust weight [0.0–1.0] [required]
Options:
--help: Show this message and exit.
particles extractor benchmark¶
Run extraction-quality benchmarks against an extractor.
Discovers every suite under --suites-dir that this extractor is the
production routing choice for: the registry ladder, read back
through select_extractor, so the fallback extractor no
longer inherits every domain suite. --suite runs a named suite
regardless of routing. Emits one report per suite, and persists each
report as a JSON file under benchmark.runs_dir (stamped with the
resolved extraction provider:model pairing) unless --no-save is set.
With --fail-on set, exits non-zero when any suite's named metric
crosses the threshold.
--runs N repeats each suite N times and reports each metric's mean,
range and standard deviation instead of a single point estimate: the
error bars a provider comparison needs. Every pass persists
its own report file, so the series is still one run per JSON envelope.
--fail-on is evaluated against the mean across runs.
Usage:
Arguments:
extractor_id: EXTRACTOR_ID of a registered extractor [required]
Options:
--suite <str>: Run only the suite with this suite_id (default: every suite the extractor is the routing choice for)--suites-dir <path>: Override suite directory (default: tests/benchmark/suites)--fixtures <path>: Override fixture directory used to resolvefixture:references (default: tests/conformance/fixtures)--judge <embedding|llm>: Equivalence judge: embedding cosine (default) or LLM-judge [default: embedding]--threshold <float range>: Cosine-similarity threshold for the embedding judge [default: 0.8; 0.0<=x<=1.0]--format <table|json>: Output format [default: table]--fail-on <none|precision|recall|calibration>: Exit non-zero when the named metric falls below --fail-threshold [default: none]--fail-threshold <float range>: Threshold for --fail-on (precision/recall: minimum; calibration: maximum) [default: 0.9; 0.0<=x<=1.0]--no-save: Skip persisting the run report JSON under benchmark.runs_dir--runs <int range>: Repeat each suite N times and report mean ± spread per metric. Costs N× the LLM calls; N=1 (default) is unchanged [default: 1; x>=1]--estimate: Print the projected LLM cost of the run and exit without running-y, --yes: Pre-confirm the cost gate for a repeat run (--runs N)--help: Show this message and exit.
particles extractor benchmark-modality¶
Measure assertion_modality classification quality.
Reports per-modality precision/recall, the dangerous false-non-FALSIFIABLE rate the journal extractor's inverted default raises, and the whole-entry narrative-emission rate. Discovers every modality suite under --suites-dir the extractor is the production routing choice for (or runs only --suite). Report-only and integration-tier: it drives the extractor's LLM call, so it needs ANTHROPIC_API_KEY.
Usage:
Arguments:
extractor_id: EXTRACTOR_ID of a registered extractor [required]
Options:
--suite <str>: Run only the modality suite with this suite_id (default: every suite the extractor is the routing choice for)--suites-dir <path>: Override modality-suite directory (default: tests/benchmark/modality)--judge <embedding|llm>: Claim-alignment judge: embedding cosine (default) or LLM-judge [default: embedding]--threshold <float range>: Cosine floor for aligning an emitted claim to a gold label (looser than the content harness's 0.80; journal claims are reified paraphrases of their gold labels) [default: 0.65; 0.0<=x<=1.0]--format <table|json>: Output format [default: table]--help: Show this message and exit.
particles extractor benchmark-polarity¶
Measure claim-polarity classification quality.
Reports the dangerous wrong-DECLINED rate, a real current decision
(ASSERTED) wrongly classified DECLINED and thereby silently hidden from the
default surface (the headline, the README-projection-trust risk;
cap. 1), plus its superset the wrong-hidden rate and per-polarity
precision/recall. Discovers every polarity suite under --suites-dir the
extractor is the production routing choice for (or runs only
--suite). Report-only and
integration-tier: it drives the extractor's LLM call, so it needs
ANTHROPIC_API_KEY.
Usage:
Arguments:
extractor_id: EXTRACTOR_ID of a registered extractor [required]
Options:
--suite <str>: Run only the polarity suite with this suite_id (default: every suite the extractor is the routing choice for)--suites-dir <path>: Override polarity-suite directory (default: tests/benchmark/polarity)--judge <embedding|llm>: Claim-alignment judge: embedding cosine (default) or LLM-judge [default: embedding]--threshold <float range>: Cosine floor for aligning an emitted claim to a gold label (looser than the content harness's 0.80; the general extractor emits near-paraphrases of its gold labels) [default: 0.65; 0.0<=x<=1.0]--format <table|json>: Output format [default: table]--help: Show this message and exit.
particles extractor benchmark-validity¶
Measure event-anchored-validity quality.
Reports the dangerous wrong-expiry rate: of the aligned claims whose
gold is durable (no boundary), the fraction the extractor wrongly assigned a
valid_until and thereby set up for silent retirement by the §9.3
staleness lint (the headline, the over-eager-expiry risk). It also reports existence
precision/recall of correct date-bounded extraction and date accuracy.
Discovers every validity suite under --suites-dir the extractor is the
production routing choice for (or runs only --suite). Report-only
and integration-tier: it drives the extractor's LLM call, so it needs
ANTHROPIC_API_KEY.
Usage:
Arguments:
extractor_id: EXTRACTOR_ID of a registered extractor [required]
Options:
--suite <str>: Run only the validity suite with this suite_id (default: every suite the extractor is the routing choice for)--suites-dir <path>: Override validity-suite directory (default: tests/benchmark/validity)--judge <embedding|llm>: Claim-alignment judge: embedding cosine (default) or LLM-judge [default: embedding]--threshold <float range>: Cosine floor for aligning an emitted claim to a gold label (looser than the content harness's 0.80; the general extractor emits near-paraphrases of its gold labels) [default: 0.65; 0.0<=x<=1.0]--format <table|json>: Output format [default: table]--help: Show this message and exit.
particles extractor benchmark-compare¶
Compare two or more extractors against the same benchmark corpus.
particles extractor benchmark-compare \
--extractor-id numista-coin-extractor \
--extractor-id numista-coin-extractor-v3
Cells where an extractor declined a suite's source_type render as
— in the table view and null in JSON output.
Usage:
Options:
--extractor-id <str>: EXTRACTOR_ID to include in the comparison (repeat ≥2 times) [required]--suite <str>: Restrict to a single suite_id (default: every suite whose source_types intersect ANY supplied extractor's accepts())--suites-dir <path>: Override suite directory (default: tests/benchmark/suites)--fixtures <path>: Override fixture directory (default: tests/conformance/fixtures)--judge <embedding|llm>: Equivalence judge: embedding cosine (default) or LLM-judge [default: embedding]--threshold <float range>: Embedding-judge cosine threshold [default: 0.8; 0.0<=x<=1.0]--format <table|json>: Output format [default: table]--help: Show this message and exit.
particles extractor calibrate¶
Fit a temperature-scaling calibration for an extractor.
Runs every applicable calibration suite (tests/benchmark/calibration/,
a sibling of the §13.3 suites/ directory whose gold sets are deliberately
partial), collects (raw_confidence, correct) pairs from
emitted-vs-matched, fits a single T via NLL minimisation, and persists the
result on the extractor record. Subsequent particles produced by this
extractor carry calibration_source=CALIBRATED_BENCHMARK and a
temperature-scaled confidence value. Pre-existing particles are
unaffected; operators who want retroactive application should run
particles reindex --extractor-id <id>.
The fit is refused rather than persisted when it cannot mean anything: degenerate labels, a temperature on an optimizer bound, fewer than two distinct movable confidences, or a calibration that does not reduce calibration error.
It is also refused when it does not hold up out of sample. The
fitted temperature is scored on every recorded extractor benchmark run
under benchmark.runs_dir for the same extractor, extractor version and
extraction provider:model, and a fit that raises their calibration error
is not persisted. With no such run the fit is refused as well, so run
particles extractor benchmark <id> --runs 3 first under the same
configuration. Reading those runs makes no LLM call.
Unlike extractor benchmark, this verb defaults to the LLM equivalence
judge; see _extractor_calibrate for why the calibration label
cannot afford the embedding judge's paraphrase misses.
Usage:
Arguments:
extractor_id: EXTRACTOR_ID of a registered extractor [required]
Options:
--suite <str>: Restrict calibration to a single suite_id (default: every suite the extractor is the routing choice for)--suites-dir <path>: Override suite directory (default: tests/benchmark/calibration)--fixtures <path>: Override fixture directory used to resolvefixture:references (default: tests/conformance/fixtures)--judge <embedding|llm>: Equivalence judge for the calibration label: LLM-judge (default) or embedding cosine [default: llm]--dry-run / --no-dry-run: Fit and print but do not persist the calibration record [default: no-dry-run]--regenerate / --no-regenerate: Overwrite an existing calibration; without it, an extractor that already has one exits 1 [default: no-regenerate]--runs <int range>: Fit over the pooled pairs from N independent passes instead of one. A single pass is a noisy estimator (measured T spread 1.86-2.60 against a pooled 2.15), so N>1 persists the centre of the distribution rather than a draw from it. Small N is not enough: ~13 passes was the measured requirement on that suite, and a pooled fit over 3 was still refused. Costs N× the LLM calls [default: 1; x>=1]-y, --yes: Pre-confirm the cost gate for a pooled fit (--runs N)--help: Show this message and exit.
particles extractor calibrations¶
List stored calibrations per (provider, model) for an extractor.
Each extractor calibrate run stores one record keyed by the extraction
model it ran under, so several models' calibrations coexist; the one matching
the configured extraction model is applied at extraction time.
A record applies only under the extractor version it was fitted under. One fitted under another version, or persisted before the version was recorded, is listed as NOT APPLIED with both versions named.
Each record is checked for suite-set staleness: a fit whose contributing suites differ from the ones the extractor auto-matches today answers a question it is no longer asked. The check needs the benchmark suites, which ship in neither the wheel nor the sdist, so on an installed SDK the listing prints unannotated.
Usage:
Arguments:
extractor_id: Extractor id to list calibrations for [required]
Options:
--suites-dir <path>: Override suite directory used to report suite-set staleness (default: tests/benchmark/calibration)--help: Show this message and exit.
particles extractor calibration-forget¶
Retire one stored calibration record.
The counterpart to extractor calibrate. Before this verb a stored
calibration could only be replaced, by re-fitting under the same
pairing, so a record fitted against a model no longer reachable (a local
endpoint since torn down) could not be retired at all without standing
that model back up.
Removing a record returns that pairing to calibration_source=
EXTRACTOR_DIRECT, the documented fallback for an uncalibrated pairing.
Particles already in the store keep the confidence they were minted with;
run particles reindex --extractor-id <id> to re-mint them.
Usage:
Arguments:
extractor_id: EXTRACTOR_ID the calibration belongs to [required]provider_model: The ": " pairing to retire, as printed by extractor calibrations[required]
Options:
-y, --yes: Skip the confirmation prompt (for scripted use)--help: Show this message and exit.
particles hook¶
Machine-facing Claude Code lifecycle hooks. Reads the hook JSON from stdin; degrades to exit 0 on any failure.
Usage:
Options:
--help: Show this message and exit.
Commands:
session-start: SessionStart hook: push the memory digest...session-end: SessionEnd hook: harvest the session...log: Print recent hook-log entries (one JSONL...doctor: Diagnose whetherparticles hook...
particles hook session-start¶
SessionStart hook: push the memory digest into the session's context.
Usage:
Options:
--store <str>: Memory store whose digest is pushed. [required]--help: Show this message and exit.
particles hook session-end¶
SessionEnd hook: harvest the session transcript + memory files.
Usage:
Options:
--store <str>: Memory store the harvest deposits into. [required]--help: Show this message and exit.
particles hook log¶
Print recent hook-log entries (one JSONL line per hook invocation).
Usage:
Options:
-n, --tail <int>: How many recent entries to print. [default: 20]--help: Show this message and exit.
particles hook doctor¶
Diagnose whether particles hook resolves store from the current directory.
The lifecycle hooks degrade to exit 0 on any failure, so a mis-resolved store fails silently. This verb makes that resolution visible: which config.yaml is found, which DSN the handle resolves to, whether the DB file exists and carries the corpus tables. Exits non-zero when the store is unusable, so it can gate an operator's "is this thing on?" check.
Usage:
Options:
--store <str>: Store handle to check. [default: default]--help: Show this message and exit.
particles import¶
Bulk-onboard existing knowledge bases.
Usage:
Options:
--help: Show this message and exit.
Commands:
vault: Walk a Markdown vault and deposit every...project: Walk a project tree and deposit every...web-clipper: Walk a frontmatter-Markdown captures...mcp-memory: Deposit a reference memory-server...
particles import vault¶
Walk a Markdown vault and deposit every .md file as LOCAL_MARKDOWN.
Recursively walks vault_dir (skipping any path under a _ or .
component: Obsidian's .obsidian/ settings, _attachments/, etc.)
and registers each Markdown file in the corpus. Re-running on the same
vault is idempotent: existing content_hash deduplication means
unchanged files are not re-deposited.
Typical onboarding workflow:
particles import vault ~/Documents/MyVault
particles extract --all-pending
particles lint
Usage:
Arguments:
vault_dir: Path to an Obsidian vault (or any directory of Markdown notes). [required]
Options:
--deposited-by <str>: Agent or operator ID. [default: operator]--tags <str>: Comma-separated tags applied to every deposited entry.-v, --verbose: Print per-file progress while depositing.--debug: Show DEBUG-level logs from deposit/fetch.--help: Show this message and exit.
particles import project¶
Walk a project tree and deposit every source file as PYTHON_SOURCE.
Recursively walks project_dir for source files (.py by default; see
import_project.extensions), skipping dot-prefixed components and the
configured build/cache directories (import_project.ignore_dirs), but
keeping underscore-prefixed module files (__init__.py / _shared.py).
Re-running on the same tree is idempotent: content_hash deduplication
means only changed files get a new snapshot.
Typical onboarding workflow:
particles import project ~/src/myproject
particles extract --all-pending # docstring extractor runs
particles lint # code/design drift surfaces
Usage:
Arguments:
project_dir: Path to a software-project tree (walked recursively). [required]
Options:
--deposited-by <str>: Agent or operator ID. [default: operator]--tags <str>: Comma-separated tags applied to every deposited entry.--ext <str>: Comma-separated file extensions to deposit this run (e.g. '.py'), overriding the configured import_project.extensions set.-v, --verbose: Print per-file progress while depositing.--debug: Show DEBUG-level logs from deposit/fetch.--help: Show this message and exit.
particles import web-clipper¶
Walk a frontmatter-Markdown captures folder and deposit each as WEB_PAGE.
Recursively walks captures_dir (skipping any path under a _ or .
component, the vault ignore policy) and deposits each .md capture with the
provenance its frontmatter carries restored: the source: / url: URL
becomes the entry's uri_r (fragment-stripped, not fetched), the
published: date becomes content_published_at (below an
explicit operator date), the frontmatter tags: merge with --tags, and
the source type is WEB_PAGE, so a clipping is trustable, decayable, and
queryable as the web page it is, unlike the same folder run through
import vault. The frontmatter-stripped body is the deposited content.
A capture whose header is absent / malformed falls back to a plain
LOCAL_MARKDOWN body deposit. Re-running is idempotent (body-hash dedup).
Typical onboarding workflow:
particles import web-clipper ~/Obsidian/Clippings
particles extract --all-pending
particles lint
Usage:
Arguments:
captures_dir: Path to an Obsidian Web Clipper captures folder (walked recursively). [required]
Options:
--deposited-by <str>: Agent or operator ID. [default: web-clipper]--tags <str>: Comma-separated tags merged with each capture's frontmatter tags.-v, --verbose: Print per-file progress while depositing.--debug: Show DEBUG-level logs from deposit/fetch.--help: Show this message and exit.
particles import mcp-memory¶
Deposit a reference memory-server memory.jsonl for migration.
Brings an existing @modelcontextprotocol/server-memory graph across:
entities become Subjects, observations become single-subject particles, and
relations become two-subject particles, the same encoding
particles memory serve reads, so a migrated graph is visible
through the façade immediately.
The export is deposited verbatim as an MCP_MEMORY_EXPORT entry
(STABLE / NEVER: a dump is a record of what was seen, not a live
handle), and every particle points back at it by line number. Nothing is
attributed to the incumbent store itself: the SDK never fetched it and
cannot re-verify it, so provenance names the artifact it actually holds.
Re-running is idempotent (content-hash dedup).
One thing does not come across: an entity with no observations that no relation names. A store holds a name only through something believed about it, so there is nothing to attach it to. The verb lists those entities when it runs; an observation-less entity that is a relation endpoint migrates, with its type.
Migrated beliefs are deliberately low-confidence: they are second-hand, and
the incumbent's own scores are preserved as tags rather than becoming
confidence values. Raise them with particles trust set once you vouch
for the source, not by editing the import floor.
Run it with --dry-run first. That parses the export and runs the same
mapping the import runs, then prints what it would produce: entities to
Subjects, records to particles, everything the mapping drops (including
the entities that will not migrate, by name), and a sample. It
opens no store and deposits nothing, so it is safe on a store you care
about and needs no particles db init. Its counts are what the export
contributes: on a store that already holds part of it, Subjects re-attach
and identical claims dedup, so the real import writes no more than this.
particles import mcp-memory ~/.mcp/memory.jsonl --dry-run
particles import mcp-memory ~/.mcp/memory.jsonl
particles extract --all-pending
particles lint
Usage:
Arguments:
export_path: Path to a reference memory-server memory.jsonl export. [required]
Options:
--deposited-by <str>: Agent or operator ID performing the import. [default: operator]--tags <str>: Comma-separated tags added to the corpus entry.--dry-run: Report what the import would produce (counts, what is dropped, a sample) without depositing or writing anything.--sample <int range>: With --dry-run: how many mapped records to show. [default: 5; x>=0]--json: With --dry-run: emit the report as JSON instead of text.--debug: Show DEBUG-level logs from deposit.--help: Show this message and exit.
particles inbox¶
Process URLs queued from an iOS Shortcut via iCloud Drive.
Usage:
Options:
--help: Show this message and exit.
Commands:
process: Process all pending URLs in the inbox...watch: Continuously poll the inbox file.status: Show pending vs processed counts in the...
particles inbox process¶
Process all pending URLs in the inbox file, then exit.
Suitable for cron / launchd / a desktop keyboard shortcut. Each
pending URL is deposited and the inbox line is rewritten in place
with the resulting entry_id.
Usage:
Options:
--deposited-by <str>: Recorded as the depositor on each entry. [default: inbox]--help: Show this message and exit.
particles inbox watch¶
Continuously poll the inbox file. Ctrl-C to stop.
Uses mtime to skip the file read when nothing has changed since the last poll, cheap enough to leave running in a terminal tab.
Usage:
Options:
--interval <int>: Seconds between polls. Defaults to inbox.poll_interval_seconds (30).--deposited-by <str>: Recorded as the depositor on each entry. [default: inbox]--help: Show this message and exit.
particles inbox status¶
Show pending vs processed counts in the inbox file.
Usage:
Options:
--help: Show this message and exit.
particles init¶
Install (or remove) an agent-harness memory integration.
Usage:
Options:
--help: Show this message and exit.
Commands:
claude-code: Install the Claude Code hook integration...
particles init claude-code¶
Install the Claude Code hook integration (SessionStart digest push + SessionEnd harvest).
Usage:
Options:
--store <str>: Memory store handle baked into the hook commands. Default: the single mcp.write.enabled_stores entry; a fresh install auto-creates 'memory'.--project: Install into the current repo's .claude/settings.local.json (gitignored) instead of the user-level ~/.claude/settings.json.--remove: Remove exactly the Particles-owned hook entries (and revert the store auto-create while the store is still empty).--dry-run: Print the resulting files without writing anything.--command <str>: Override the hook command base (default: the absolute path of the runningparticlesconsole script).--no-audit: Skip the first-run memory-audit hand-off.--skills / --no-skills: Install the shipped agent-onboarding skill files too, into the harness's skills directory (a Particles-owned subdirectory; --remove deletes exactly that). Default on: an agent that has the tools but not the guidance is the gap these close. [default: skills]--json: Emit a machine-readable result on stdout (what was created, what was merged, and what is left for the human) so an agent can run the installer and report the outcome instead of scraping human-formatted output. Implies --no-audit: the audit hand-off is interactive, and the result names it under next_steps.--help: Show this message and exit.
particles interchange¶
Export / import portable store bundles.
Usage:
Options:
--help: Show this message and exit.
Commands:
export: Write a store-export bundle (manifest +...import: Import a store-export bundle into a store...restore: Faithfully reconstruct a bundle into an...
particles interchange export¶
Write a store-export bundle (manifest + particles/subjects members).
Usage:
Options:
-o, --output <path>: Bundle directory to write [required]--store <str>: Store handle to export [default: default]--format <str>: Bundle container: jsonl (canonical, one unit per line) or yaml (human-editable YAML-LD, same data model). Both round-trip throughinterchange importunchanged. [default: jsonl]--help: Show this message and exit.
particles interchange import¶
Import a store-export bundle into a store (single-store writes, §6.6).
Usage:
Arguments:
bundle: Bundle directory to import [required]
Options:
--store <str>: Target store handle [default: default]--help: Show this message and exit.
particles interchange restore¶
Faithfully reconstruct a bundle into an EMPTY store, origin ids preserved.
Unlike import (claim-fingerprint merge, fresh ids), restore reconstructs
the bundle's own store: ids are preserved verbatim and no §6.6 reconcile runs.
The target must be empty; a populated target is refused.
Usage:
Arguments:
bundle: Bundle directory or a single particles JSONL file to restore [required]
Options:
--store <str>: Target store handle (must be empty) [default: default]--help: Show this message and exit.
particles links¶
Manage typed relations between particles (e.g. co-evidential links).
Usage:
Options:
--help: Show this message and exit.
Commands:
add: Create a typed relation between two...remove: Remove a typed relation between two...list: List all relations incident to a particle,...suggest: Propose (and optionally resolve)...dedup: Merge identical-content duplicate beliefs...unmerge: Revert an exact-duplicate auto-merge,...
particles links add¶
Create a typed relation between two particles.
Usage:
Arguments:
particle_a: Particle A ID (prefix OK, ≥ 8 chars) [required]particle_b: Particle B ID (prefix OK, ≥ 8 chars) [required]
Options:
--type <str>: Relation type: co-evidential, part-of, or sequence-in. part-of / sequence-in are directional (A → B). [default: co-evidential]--confidence <float range>: Link confidence in [0, 1]. Defaults to 1.0 for manual operator links. [default: 1.0; 0.0<=x<=1.0]--help: Show this message and exit.
particles links remove¶
Remove a typed relation between two particles.
Usage:
Arguments:
particle_a: Particle A ID (prefix OK, ≥ 8 chars) [required]particle_b: Particle B ID (prefix OK, ≥ 8 chars) [required]
Options:
--type <str>: Relation type to remove. [default: co-evidential]--help: Show this message and exit.
particles links list¶
List all relations incident to a particle, and its full co-evidential group.
Usage:
Arguments:
particle_id: Particle ID (prefix OK, ≥ 8 chars) [required]
Options:
--kind <str>: Filter to one relation kind (e.g. co-evidential, part-of, endorses). Case-insensitive; hyphens and underscores both accepted.--help: Show this message and exit.
particles links suggest¶
Propose (and optionally resolve) co-evidential candidate links.
Usage:
Options:
--subject <str>: Restrict to one Subject (ID or canonical name).--all: Scan every Subject. Mutually exclusive with --subject.--threshold <float range>: Cosine-similarity floor (default: links_suggest.candidate_threshold). [0.0<=x<=1.0]--llm-judge: Send each Subject's candidate cluster to the LLM for per-pair verdicts.--apply: Implies --llm-judge; auto-link PARAPHRASE pairs (needs --yes past the cap).--yes: Confirm --apply when it would link more than apply_confirm_threshold pairs.--output-format <str>: Output format: markdown or json [default: markdown]--help: Show this message and exit.
particles links dedup¶
Merge identical-content duplicate beliefs into one survivor.
Exact content equality only, the same normalized key extract-time suppression uses (whitespace and trailing punctuation absorbed, wording and case preserved), so no similarity threshold and no LLM call. Redundant copies are linked CO_EVIDENTIAL to the survivor and superseded; nothing is ever deleted and the survivor is never mutated.
Usage:
Options:
--subject <str>: Restrict to one Subject (ID or canonical name). Default: whole store.--apply: Merge the groups. Requires links_suggest.auto_merge.enabled in config.yaml. Without this flag the run is a read-only census.--output-format <str>: Output format: markdown or json [default: markdown]--limit <int>: Groups listed in markdown output (counts are always complete). [default: 20]--help: Show this message and exit.
particles links unmerge¶
Revert an exact-duplicate auto-merge, restoring the superseded copies.
The exact inverse of links dedup --apply: the retained copies return to
ACTIVE keeping their ids, the merge's own CO_EVIDENTIAL links are dropped,
and the survivor is never touched. Copies that moved on since the merge are
skipped and named rather than restored.
Usage:
Arguments:
event_id: The DUPLICATES_MERGED event to revert (fromparticles events list).
Options:
--run <str>: Revert every merge stamped with this run id instead of one event.--since <%Y-%m-%d|%Y-%m-%dT%H:%M:%S>: Revert every merge at or after this instant. For merges written before run ids existed.--until <%Y-%m-%d|%Y-%m-%dT%H:%M:%S>: Exclusive upper bound for --since.--dry-run: Show the plan without writing-y, --yes: Skip the confirmation prompt--output-format <str>: Output format: markdown or json [default: markdown]--limit <int>: Groups listed in markdown output (counts are always complete). [default: 20]--help: Show this message and exit.
particles mcp¶
Model Context Protocol server (read-only).
Usage:
Options:
--help: Show this message and exit.
Commands:
serve: Run the Particles MCP server over stdio.tools: Print the registered MCP tool surface...resources: Print the registered MCP resource surface...
particles mcp serve¶
Run the Particles MCP server over stdio.
Typical install path on the operator's machine::
claude mcp add particles -- uv run particles mcp serve --project-observer cwd
--project-observer cwd is a launch flag, not configuration, on purpose:
config.yaml is shared by every MCP client on the machine, and a client
started from your home directory should not be bound to it.
Usage:
Options:
--project-observer cwd: Bind this server to the project of its working directory (the only value iscwd): reads see global beliefs plus that project's, and writes are attributed to it. Omit for the store-wide server.--help: Show this message and exit.
particles mcp tools¶
Print the registered MCP tool surface (name, description, input schema).
Used to verify the contract without spawning an MCP client. The JSON
output is what tests/mcp/tool-schema.json should match; drift
here means an operations/ signature changed and the MCP surface
needs review.
Usage:
Options:
--format <str>: Output format: "json" (default) or "text". [default: json]--help: Show this message and exit.
particles mcp resources¶
Print the registered MCP resource surface (digest).
The sibling of particles mcp tools for the resources primitive: the
particles://digest/{store} template plus any concrete per-store digests
listed for the write-enabled / opted-in memory stores. The JSON output is
what tests/mcp/resource-schema.json should match; drift here means the
resource contract MCP clients see has changed.
Usage:
Options:
--format <str>: Output format: "json" (default) or "text". [default: json]--help: Show this message and exit.
particles memory¶
Agent-memory maintenance.
Usage:
Options:
--help: Show this message and exit.
Commands:
rebuild-utility: Re-mine harvested session transcripts into...useful: Mark a belief useful: the explicit utility...rescope: Bring a store's project keys up to date,...widen: Put a belief in view for every project...sweep-rank-lift: Sweep the usefulness rank-lift and report...consolidate: Run the scheduled consolidation cycle (ADR...serve: Serve the reference memory-server...tools: Print the façade's tool surface: name,...sweep-owner-lift: Sweep the owner-relevance rank-lift and...
particles memory rebuild-utility¶
Re-mine harvested session transcripts into fresh utility evidence.
A belief is credited only when the session was shown it and an LLM judge
rules that the session's actions applied it. A literal token match only
nominates a candidate for the judge. The command plans every session
first and prints the judge calls and their list-price cost before it
clears anything. With utility.mining.behavioural_matching off the judge
never runs, so a literal-only rebuild now records no mined events. The
explicit channel (memory useful) is rebuilt from its event log either way.
Usage:
Options:
--store <str>: Store handle to rebuild utility evidence for. [default: default]-y, --yes: Skip the cost confirmation and start the re-mine.--batch / --no-batch: Send the judge calls as one half-price batch (the default), or one at a time. [default: batch]-v, --verbose: Raise diagnostics to INFO and un-aggregate per-item detail.--debug: Full DEBUG diagnostics and tracebacks (implies --verbose).-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
particles memory useful¶
Mark a belief useful: the explicit utility gesture.
Use this for the beliefs the transcript miner cannot see: prohibitions
("never do X") and design stances, which you comply with by not acting and
which therefore leave no tool-call trace. One press is worth
utility.explicit_weight mined events, because the miner fires once per
session while you fire once. It is capped at one credit per belief per
day, so pressing twice is recorded but not double-counted.
This lifts the belief in the projection and digest ranking only. It never
touches the stored confidence, never claims the belief is true, and can
only promote. For "still true", the gesture is
particles curate apply affirm.
Usage:
Arguments:
PARTICLE_ID: The belief that earned its place. Full UUID, a unique id prefix, or thep-xxxxxxxxdisplay form the digest andparticle showprint. [required]
Options:
--reason <str>: Optional note recorded on the operator event.--store <str>: Store handle. [default: default]-v, --verbose: Raise diagnostics to INFO and un-aggregate per-item detail.--debug: Full DEBUG diagnostics and tracebacks (implies --verbose).-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
particles memory rescope¶
Bring a store's project keys up to date, so a project observer can read it.
A belief is in view for a project when one of its sources was harvested
there, which is read from the project: tag on the source's corpus entry.
Older versions stamped a per-worktree name, or nothing at all. This verb
adds the project's real key beside whatever an entry already carries. It
never removes a tag, and running it twice changes nothing.
It reports the two things you need to see: harvested entries it could not
attribute (in view for no project until you --assign them or pass
--default-key), and entries whose every key names a project that no longer
exists. particles init claude-code runs it for you. Until it has run once,
claude_code.observer_scope: project stays store-wide and says so.
Usage:
Options:
--assign ENTRY_ID KEY: Give one corpus entry a project key, then stop. Refuses a global entry.--default-key KEY: Give this key to every harvested entry that is still unattributed afterwards. On a one-project machine this is the one flag you need;.means the project of the current directory.--dry-run: Report what would change; write nothing.--store <str>: Store handle. [default: default]-v, --verbose: Raise diagnostics to INFO and un-aggregate per-item detail.--debug: Full DEBUG diagnostics and tracebacks (implies --verbose).-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
particles memory widen¶
Put a belief in view for every project.
"This rule I learned in one project is how I work everywhere" is your
judgement, so it is yours to record. The belief and its sources are not
touched: the widening is a standing statement the read lens consults, and
--revoke withdraws it. There is deliberately no agent-facing way to do
this: an agent that could widen its own belief could put it in front of
every future session.
Usage:
Arguments:
ID: The belief (full UUID, unique prefix, orp-xxxxxxxx); with --entry, a corpus entry id. [required]
Options:
--entry: ID is a corpus entry: widen every belief sourced from it.--revoke: Take a widening back.--store <str>: Store handle. [default: default]-v, --verbose: Raise diagnostics to INFO and un-aggregate per-item detail.--debug: Full DEBUG diagnostics and tracebacks (implies --verbose).-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
particles memory sweep-rank-lift¶
Sweep the usefulness rank-lift and report its admissible band.
Read-only: no writes, no LLM calls, no embeddings. λ
(utility.default.rank_lift) is deliberately not auto-fitted: every
candidate closed form was measured and none found defensible,
because no label says which belief should occupy a head slot. This is the harness
that makes setting it by hand a single command instead of a research
project: name the beliefs that ought to reach the head with --target, and
the sweep reports where they land, how many head slots hold distinct
content, the resulting band per surface, and whether the configured value
is inside it.
Usage:
Options:
--store <str>: Store handle to sweep. [default: default]--target <str>: Particle id of a belief you assert ought to reach the head; repeatable. Full UUID, a unique id prefix, or thep-xxxxxxxxdigest display form; resolved against ACTIVE beliefs, and an id that matches none (or more than one) is an error rather than a silent rank-0. This is the judgment a fit cannot supply; without any, only head diversity constrains the band.--head <int>: A rendered head size N to evaluate; repeatable. Defaults to the digest's mcp.recall.digest_max_beliefs. Pass every N you actually render; the band is a property of the surface, not the store.--grid-max <float>: Largest lambda to evaluate. [default: 0.12]--grid-steps <int>: Non-zero grid points; band edges resolve to one step. [default: 120]--distinct-ratio <float>: Fraction of head slots that must hold distinct content. Not 1.0; that is unsatisfiable at large N on any store with over-extraction. [default: 0.95]--format <str>: Output format: markdown (default) or json. [default: markdown]-v, --verbose: Raise diagnostics to INFO and un-aggregate per-item detail.--debug: Full DEBUG diagnostics and tracebacks (implies --verbose).-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
particles memory consolidate¶
Run the scheduled consolidation cycle: the memory dream cycle.
With consolidation.budget_usd set, a pass whose estimate would carry the run past the budget is skipped and disclosed. --dry-run prints each pass's estimate without running it; compare it with the "LLM usage" line a metered run prints.
On a terminal the status line names the running pass (pass 2/12 extract), its own counter, and any Message Batches wait with the batch-wait budget left; each pass prints one line as it ends. Off a terminal, and under --quiet, none of this is printed.
Every run ends with a read-only measure: the share of ACTIVE beliefs under the contested badge, and how many lifecycle transitions since the previous run were autonomous rather than caused by a gesture. Both are written to the run record; --history prints the series.
Exit codes (cron observability): 0 means success, including disclosed structural-only runs and --if-due / lock skips; 1 means one or more passes failed (run record written); 2 means the cycle could not start.
Usage:
Options:
--store <str>: Store handle to consolidate (default: the default store). [default: default]--if-due: Exit 0 without running unless the last successful run is older than consolidation.min_interval_hours; makes over-scheduling harmless.--structural-only: Skip all LLM passes (disclosed in the report and the run record).--scope <str>: Semantic-pass scope: 'delta' (default; particles changed since the previous run's watermark) or 'store' (the whole store, still capped). [default: delta]--output <path>: Write the run report as Markdown to FILE as well.--format <str>: Terminal format: markdown (default) or json. [default: markdown]--dry-run: Run each pass's gather only and report the snapshots and pairs it would extract or probe, with a list-price estimate per pass. Writes nothing and makes no LLM call.--history: Print the contested fraction and the autonomous share of lifecycle transitions that each past run recorded, oldest first. Runs nothing.-v, --verbose: Raise diagnostics to INFO and un-aggregate per-item detail.--debug: Full DEBUG diagnostics and tracebacks (implies --verbose).-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
particles memory serve¶
Serve the reference memory-server compatibility façade over stdio.
The drop-in swap for @modelcontextprotocol/server-memory: same nine
tools, same schemas, same responses, backed by a Particles store. In your
MCP client config, replace the reference server's command with::
"memory": {"command": "uv",
"args": ["run", "--project", "/path/to/particles",
"particles", "memory", "serve"]}
Args:
store: Store handle to bind. Defaults to the default store. Writes
additionally require the store to be listed in
mcp.write.enabled_stores (default-deny); the write
tools stay visible either way and refuse with an actionable
message when it is not.
Usage:
Options:
--store <str>: Store handle to bind (default: the default store).--help: Show this message and exit.
particles memory tools¶
Print the façade's tool surface: name, title, schemas, annotations.
The debugging sibling of particles mcp tools, and the generator for
tests/mcp/memory-tool-schema.json. That golden is what turns a parity
regression into a failed build instead of a broken agent.
Args:
output_format: json (default) or text for a one-line summary.
Usage:
Options:
--format <str>: Output format: "json" (default) or "text". [default: json]--help: Show this message and exit.
particles memory sweep-owner-lift¶
Sweep the owner-relevance rank-lift and report its band.
Read-only: no writes, no LLM calls, no embeddings. ω
(owner_lens.rank_lift) is store-specific and deliberately ships 0.0
(inert); this is the harness for choosing it. Unlike the utility lift, ω
multiplies a flat 0/1 indicator, so it acts as a threshold over the whole
viewer cohort: below it nothing moves, above it every belief about the
viewer arrives in the head at once. The report is therefore keyed on the
cohort's share of the head, and the utility λ in force is held fixed
so the non-regression criterion is measured against the head utility has
already shaped.
Usage:
Options:
--store <str>: Store handle to sweep. [default: default]--target <str>: Particle id of a belief that must STAY in the head; repeatable. Pass the beliefs your utility lift was calibrated to surface; the third criterion is that adding aboutness does not push them out. Same id forms assweep-rank-lift.--head <int>: A rendered head size N to evaluate; repeatable. Defaults to the digest's mcp.recall.digest_max_beliefs.--grid-max <float>: Largest omega to evaluate. [default: 0.12]--grid-steps <int>: Non-zero grid points; band edges resolve to one step. [default: 120]--min-owner <int>: Viewer beliefs the head must hold for an omega to pass (criterion 1). [default: 1]--max-owner-share <float>: Largest fraction of the head the viewer cohort may occupy (criterion 2). This is the quantity to calibrate against: A(p) is a flat step, so omega behaves as a threshold over the whole cohort rather than a graded lift. [default: 0.5]--format <str>: Output format: markdown (default) or json. [default: markdown]-v, --verbose: Raise diagnostics to INFO and un-aggregate per-item detail.--debug: Full DEBUG diagnostics and tracebacks (implies --verbose).-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
particles particle¶
Inspect individual extracted particles.
Usage:
Options:
--help: Show this message and exit.
Commands:
show: Show one particle's content, status,...source: Show the source passage a particle was...narrative: Show a NARRATIVE particle's constituents...tag: Add taxonomy tags to a particle.untag: Remove taxonomy tags from a particle (ADR...retract: Retract one belief under operator...reclassify: Set one claim's adjudicability default by...search: List particles sharing a context...
particles particle show¶
Show one particle's content, status, confidence, subjects, and source URL.
Usage:
Arguments:
particle_id: Particle ID (prefix OK, first 8 chars) [required]
Options:
--help: Show this message and exit.
particles particle source¶
Show the source passage a particle was extracted from.
Re-derives the passage from the stored snapshot, reading nothing from the
original location. The match line says how it was found: exact is the
chunk the extractor saw, verified by its recorded hash; located is the
paragraph sharing the most terms with the belief (short documents record
no chunk hash, so this is the usual result for them) and is a reading aid,
not verification; whole source means no passage stood out. Metadata is
written to stderr, so stdout carries only the passage text.
Usage:
Arguments:
particle_id: Particle ID (prefix OK, first 8 chars) [required]
Options:
--help: Show this message and exit.
particles particle narrative¶
Show a NARRATIVE particle's constituents in SEQUENCE_IN order.
With --synthesize, render the narrative as one cited prose article by
traversing its SEQUENCE_IN chain. This is the same synthesis engine the
wiki/Obsidian exporters use, here scoped to a single narrative.
Usage:
Arguments:
particle_id: NARRATIVE particle ID (prefix OK, ≥ 8 chars) [required]
Options:
--synthesize: Render the narrative as one cited prose article instead of listing its constituents.--help: Show this message and exit.
particles particle tag¶
Add taxonomy tags to a particle.
Usage:
Arguments:
particle_id: Particle ID (prefix OK) [required]
Options:
--tag <str>: Tag path to add (repeatable, e.g. coins/germany) [required]--force: Allow tags that aren't in any active taxonomy--supersede: Reserved for the immutable-revision audit trail (not yet implemented)--help: Show this message and exit.
particles particle untag¶
Remove taxonomy tags from a particle.
Usage:
Arguments:
particle_id: Particle ID (prefix OK) [required]
Options:
--tag <str>: Tag path to remove (repeatable) [required]--supersede: Reserved for the immutable-revision audit trail (not yet implemented)--help: Show this message and exit.
particles particle retract¶
Retract one belief under operator authority.
The narrow escape hatch beside the cross-asserter guardrail:
corpus retract retires every live particle from a source, and flipping
mcp.write.allow_cross_asserter would widen what every future agent
session may mutate in order to fix one row. This retires exactly one.
ACTIVE → RETRACTED with reason EXPLICIT_RETRACTION, routed through
update_particle_status so the retired_at stamp and the
PARTICLE_RETRACTED event (carrying --reason) are both
written. An operator-asserted (HUMAN_REVIEW) claim is retractable too;
a HUMAN_REVIEW REVIEW record is not, since revising one is
Review's job. Run particles lint afterwards to cascade
PROVENANCE_STALE to anything that depended on it.
Usage:
Arguments:
particle_id: Particle ID (prefix OK, first 8 chars) [required]
Options:
--reason <str>: Why this belief is being retired; recorded in the event log [required]--dry-run: Show the plan without writing-y, --yes: Skip the confirmation prompt--help: Show this message and exit.
particles particle reclassify¶
Set one claim's adjudicability default by operator verdict.
The default (assertion_modality) decides whether the write path may
arbitrate the claim against another: only FALSIFIABLE claims are compared,
superseded, or filed as an INCONSISTENCY. The extractor sets it once; this
verb corrects it for one claim. The verdict is pinned: particles modality
never overwrites it. The event log records a MODALITY_RECLASSIFIED event
with the reason and the prior and new values.
Content, confidence, provenance and status do not change. A claim an
earlier arbitration retired stays retired. The next particles memory
consolidate run re-pairs the claim under its new default.
Usage:
Arguments:
particle_id: Particle ID (prefix OK, first 8 chars) [required]
Options:
--modality <str>: The new default: FALSIFIABLE, EVALUATIVE, EXPERIENTIAL, or CONSTITUTIVE [required]--reason <str>: Why the default is wrong; recorded in the event log [required]--dry-run: Show the plan without writing--help: Show this message and exit.
particles particle search¶
List particles sharing a context fingerprint.
Usage:
Options:
--fingerprint <str>: Context fingerprint (full SHA-256 hex or prefix ≥ 8 chars) [required]--limit <int>: Maximum particles to list [default: 50]--help: Show this message and exit.
particles rules¶
Operating-rule source documents tracked by this store.
Usage:
Options:
--store <str>: Store handle to report on / write to. [default: default]-v, --verbose: Raise diagnostics to INFO and un-aggregate per-item detail.--debug: Full DEBUG diagnostics and tracebacks (implies --verbose).-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
Commands:
sync: Deposit the rule-source set as MUTABLE +...
particles rules sync¶
Deposit the rule-source set as MUTABLE + LAZY corpus entries.
Usage:
Arguments:
paths...: Files or directories to register, overriding rule_sources.paths for this run. Omit to use the configured (or discovered) set.
Options:
--store <str>: Store handle to report on / write to. [default: default]--dry-run: Resolve and print the set without depositing anything.--restamp-only: Skip the deposit half; only re-apply the scope exemption to particles already extracted from the tracked set.-v, --verbose: Raise diagnostics to INFO and un-aggregate per-item detail.--debug: Full DEBUG diagnostics and tracebacks (implies --verbose).-q, --quiet: Narration off: suppress progress and non-error diagnostics.--progress / --no-progress: Liveness on stderr. Default: auto (on when stderr is a terminal).--help: Show this message and exit.
particles skills¶
Install the agent-onboarding skill files shipped with the SDK.
Usage:
Options:
--help: Show this message and exit.
Commands:
install: Install (or remove) the shipped...list: List the skill files this SDK ships, with...
particles skills install¶
Install (or remove) the shipped agent-onboarding skill files.
Usage:
Options:
--dir <path>: Skills directory to install into. Default: ~/.claude/skills (or ./.claude/skills with --project). Files land in a 'particles' subdirectory of it.--project: Install into ./.claude/skills instead of the user-level dir.--remove: Delete exactly the Particles-owned skills subdirectory.--dry-run: Print what would be written without writing it.--help: Show this message and exit.
particles skills list¶
List the skill files this SDK ships, with their first heading.
Usage:
Options:
--help: Show this message and exit.
particles synthesis-cache¶
Inspect and prune the shared article-synthesis cache.
Usage:
Options:
--help: Show this message and exit.
Commands:
list: List every cached article (subject, hash,...show: Print the cached article body(ies) +...vacuum: Delete unreachable rows: stale prompt...evict: Evict every cached article for one subject.
particles synthesis-cache list¶
List every cached article (subject, hash, prompt version, age, size).
Usage:
Options:
--help: Show this message and exit.
particles synthesis-cache show¶
Print the cached article body(ies) + metadata for one subject.
Usage:
Arguments:
subject_id: Subject ID (prefix OK) [required]
Options:
--help: Show this message and exit.
particles synthesis-cache vacuum¶
Delete unreachable rows: stale prompt versions + orphaned subjects.
Usage:
Options:
--dry-run: Report what would be removed without deleting--help: Show this message and exit.
particles synthesis-cache evict¶
Evict every cached article for one subject.
Usage:
Arguments:
subject_id: Subject ID (prefix OK) [required]
Options:
-y, --yes: Skip the confirmation prompt--help: Show this message and exit.
particles trust¶
Manage source trust rules.
Usage:
Options:
--help: Show this message and exit.
Commands:
list: List all trust rules (domain baselines and...set: Add or update a trust rule.show: Show the resolved trust score for a URI.statement-set: Write an OPERATOR_DIRECT...set-entry: Set a per-entry trust override...cascade: Re-run cascade for all OPERATOR_DIRECT...lens: Shareable trust-policy lenses.
particles trust list¶
List all trust rules (domain baselines and URL-pattern modifiers).
Usage:
Options:
--help: Show this message and exit.
particles trust set¶
Add or update a trust rule.
Usage:
Arguments:
pattern: Domain (e.g. en.wikipedia.org) or URL regex pattern [required]score: Score [0.0-1.0] for domain rows; modifier delta for --modifier [required]
Options:
--modifier: Treat score as a modifier delta, not a base score--rationale <str>: Human-readable rationale--help: Show this message and exit.
particles trust show¶
Show the resolved trust score for a URI.
Usage:
Arguments:
uri: URI to resolve trust score for [required]
Options:
--help: Show this message and exit.
particles trust statement-set¶
Write an OPERATOR_DIRECT SourceTrustStatement and trigger cascade.
Usage:
$ particles trust statement-set [OPTIONS] {domain} {source_ref_type} {source_ref_value} {trust_rank}
Arguments:
domain: Domain label (e.g. numismatics) [required]source_ref_type: Reference type: CORPUS_ENTRY | SOURCE_TYPE | AUTHOR [required]source_ref_value: Reference value (entry_id, source_type string, or author identifier) [required]trust_rank: Trust rank [0.0–1.0] [required]
Options:
--basis <str>: Human-readable rationale--help: Show this message and exit.
particles trust set-entry¶
Set a per-entry trust override (CORPUS_ENTRY scope).
Convenience over trust statement-set CORPUS_ENTRY that validates the
entry exists and infers the domain from its source_type so the override
is consulted by the §6.6 conflict cascade for that domain. Pass --domain
to override the inferred value (required when the source_type has no MUST
applicability clause, e.g. WEB_PAGE / PDF).
Usage:
Arguments:
entry_id: Corpus entry_id to override trust for [required]trust_rank: Trust rank [0.0–1.0] [required]
Options:
--domain <str>: Domain label the override applies to (default: inferred from source_type)--basis <str>: Human-readable rationale--help: Show this message and exit.
particles trust cascade¶
Re-run cascade for all OPERATOR_DIRECT SourceTrustStatements.
Usage:
Options:
--domain <str>: Scope cascade to this domain label--dry-run: Show what would be resolved without writing--help: Show this message and exit.
particles trust lens¶
Shareable trust-policy lenses. Publish via particles deposit <lens>.json.
Usage:
Options:
--help: Show this message and exit.
Commands:
list: List materialised lenses and their...show: Show a lens's full policy entries.adopt: Adopt a lens: its policy composes into...unadopt: Remove a lens adoption.
particles trust lens list¶
List materialised lenses and their adoption state.
Usage:
Options:
--help: Show this message and exit.
particles trust lens show¶
Show a lens's full policy entries.
Usage:
Arguments:
name: Lens name (seeparticles trust lens list) [required]
Options:
--help: Show this message and exit.
particles trust lens adopt¶
Adopt a lens: its policy composes into this store's trust at query time.
Usage:
Arguments:
name: Lens name to adopt [required]
Options:
--help: Show this message and exit.
particles trust lens unadopt¶
Remove a lens adoption.
Usage:
Arguments:
name: Lens name to unadopt [required]
Options:
--help: Show this message and exit.
particles vocab¶
Vocabulary documents: a store's reviewed predicate aliases, alignments and slot profiles, versioned and shareable. A document records modelling decisions for export and reporting; it never gates extraction and does not change conflict resolution.
Usage:
Options:
--help: Show this message and exit.
Commands:
list: List vocabulary documents, their current...show: Show a document's terms with their...create: Create version 1 of a vocabulary document,...propose: Suggest alias and profile candidates from...proposals: List proposals awaiting a ruling, most...confirm: Confirm proposals: the next version of...decline: Decline proposals; the document is...align: Map a term outward to an external...export: Write a document as JSON-LD, ready for...import: Import another operator's document as...adopt: Put a document in force: its alignments...unadopt: Remove an adoption.
particles vocab list¶
List vocabulary documents, their current version, and where each is adopted.
Usage:
Options:
--help: Show this message and exit.
particles vocab show¶
Show a document's terms with their aliases, alignments and profiles.
Usage:
Arguments:
name: Document name (seeparticles vocab list) [required]
Options:
--version <int>: A past version; current if unset--help: Show this message and exit.
particles vocab create¶
Create version 1 of a vocabulary document, with no terms.
Usage:
Arguments:
name: Adoption handle, a lowercase slug [required]
Options:
--prefix <str>: CURIE prefix for the minted terms [required]--namespace <str>: Dereferenceable IRI base the terms are minted under, ending in '/' or '#' [required]--publisher <str>: Who publishes it--description <str>: One-line summary--help: Show this message and exit.
particles vocab propose¶
Suggest alias and profile candidates from the store's predicates.
Reads every ACTIVE structured claim about a classed subject. Alias
candidates cluster normalised forms within one class with the local
encoder and never join opposite polarity or direction. A proposal is a
candidate until vocab confirm; nothing enters the document before then.
Usage:
Arguments:
name: Document the proposals are for [required]
Options:
--limit <int>: Candidates of each kind to record (default vocabulary.propose_limit)--threshold <float>: Cosine similarity for alias clusters (default vocabulary.alias_similarity)--kind <str>: alias, profile, or all [default: all]--class <str>: Only predicates on this subject class--form <str>: Only this predicate, normalised--dry-run: Report candidates, record nothing--top <int>: Candidates of each kind to print [default: 30]--json <path>: Write every candidate as JSON--help: Show this message and exit.
particles vocab proposals¶
List proposals awaiting a ruling, most claims first.
Usage:
Arguments:
name: Only this document's proposals
Options:
--help: Show this message and exit.
particles vocab confirm¶
Confirm proposals: the next version of their document records each ruling.
Usage:
Arguments:
keys...: Proposal keys (vp-…) to confirm [required]
Options:
--kind <str>: For a profile: timeless_single, one_at_a_time or many_at_once--past <str>: For a profile: a form that records a past value of the slot (repeatable)--reason <str>: The evidence you ruled on--help: Show this message and exit.
particles vocab decline¶
Decline proposals; the document is unchanged and they are not proposed again.
Usage:
Arguments:
keys...: Proposal keys (vp-…) to decline [required]
Options:
--reason <str>: Why--help: Show this message and exit.
particles vocab align¶
Map a term outward to an external property; the term keeps its IRI.
The cardinality options record what the external source publishes, and the slot kind is read from them where they state one.
Usage:
Arguments:
name: Document name [required]term: Term local name, CURIE or IRI [required]target: External property, e.g. wdt:P551 or schema:author [required]
Options:
--match <str>: equivalent (owl:equivalentProperty, asserted), exact (skos:exactMatch) or close (skos:closeMatch) [required]--confidence <float>: Confidence in the mapping [default: 1.0]--basis <str>: The evidence the alignment rests on [required]--functional: The target is an owl:FunctionalProperty--max-count <int>: The target's published sh:maxCount--wikidata-constraint <str>: A P2302 constraint the target carries, as QID or QID:P580,P582 with its P4155 separators (repeatable)--help: Show this message and exit.
particles vocab export¶
Write a document as JSON-LD, ready for another store to import.
Usage:
Arguments:
name: Document name [required]
Options:
--version <int>: A past version; current if unset-o, --output <path>: File to write; stdout if unset--help: Show this message and exit.
particles vocab import¶
Import another operator's document as received. Importing does not adopt it.
Usage:
Arguments:
path: A JSON-LD document [required]
Options:
--help: Show this message and exit.
particles vocab adopt¶
Put a document in force: its alignments feed the store's vocabulary report.
Usage:
Arguments:
name: Document name [required]
Options:
--lens <str>: In force only while this trust lens is adopted--help: Show this message and exit.
particles vocab unadopt¶
Remove an adoption.
Usage:
Arguments:
name: Document name [required]
Options:
--lens <str>: The lens the adoption rides--help: Show this message and exit.