projectious-work Context Archiving
Intro
context-archiving manages the cold tier of processkit context. It identifies
stable archive candidates, packages their Markdown payloads into cold storage,
removes the hot files, and leaves metadata discoverable through
index-management.
Overview
Use this skill when context size is becoming expensive, old completed work is rarely read, or log/event payloads need to move from the hot tree into a cold archive while metadata remains queryable.
The cold-tier target shape is:
- Select stable entities by kind, state, and age.
- Package payload files into a content-addressed
tar.gzarchive. - Keep index rows queryable with
storage_locationpointing at the archive. - Extract full payloads on demand for historical queries.
Version 0.2.0 implements this shape with a dry-run-first archive writer and
explicit payload extraction tool.
MCP Tools
| Tool | Purpose |
|---|---|
describe_archive_policy() |
Return the default hot/warm/cold policy. |
plan_archive(kind, state, older_than_days) |
Return candidate entities from the live index. |
create_archive(kind, state, older_than_days, limit, dry_run) |
Write a tar.gz archive plus manifest, remove hot files, reindex, and log the archive event. Defaults to dry-run. |
extract_archive_payload(entity_id) |
Resolve an archived entity and return its full Markdown payload from cold storage. |
Default Policy
- WorkItems: archive terminal states after 30 days.
- DecisionRecords: keep accepted/superseded decisions hot for 90 days.
- LogEntries: shard by month; archive payload shards after 90 days.
- Migrations: archive applied or rejected history after 30 days.
- Never archive active, proposed, blocked, or in-progress entities.
- Never archive files under
context/templates/.
Gotchas
- Do not move entity files by hand. The index must keep metadata queryable
after archiving, so any write path has to update
storage_locationtransactionally. - Do not archive active state. Backlog, in-progress, blocked, proposed, and active entities belong in the hot tier.
- Treat logs as append-only. A cold log shard can be packaged, but its event identity and timestamp metadata must remain queryable forever.
- Do not trust filesystem age alone. Use entity metadata timestamps and state from the index; git checkout times are not archival age.
- Keep extraction explicit. A historical query may need full payload text, but routine status and routing queries should stay metadata-only.
Full reference
create_archive() writes two files under context/archives/YYYY/MM/: a
compressed tar payload and a JSON manifest. The manifest keeps entity metadata,
the original hot-tree path, the tar member path, a SHA-256 digest of each
payload, and the storage_location used by index-management.
After writing the manifest, the tool removes the archived hot files, rebuilds
the index, and records a context_archive.created event. dry_run=True is the
default and returns the exact candidate set without moving files.
Archived entities remain visible through normal index lookups. Use
extract_archive_payload(entity_id) only when the full historical Markdown is
needed.