Sillok

Sillok is a Rust CLI for meticulous agentic work chronicles. It records daily objectives, completed tasks, corrections, and retractions into a structured archive instead of a fragile append-only text log.

The name comes from Korean sillok, the court chronicles of Joseon. The design goal is similar: keep precise records of what happened, when, under what objective, and in what working context.

Status

Sillok is an early local-first CLI. The command interface is intended to be stable enough for agent harnesses, but the serialized archive format is private and may change.

Install

Build the binary in dev mode:

cargo build

Install it onto your PATH:

cargo install --path .

Then use:

sillok --help

Storage

By default, Sillok stores one user-global archive at:

$XDG_DATA_HOME/sillok/sillok.slk.zst

If XDG_DATA_HOME is unset, it falls back to:

~/.local/share/sillok/sillok.slk.zst

Override the store with either:

sillok --store /path/to/sillok.slk.zst day
SILLOK_STORE=/path/to/sillok.slk.zst sillok day

The current implementation persists a compressed private archive. On every mutation, it loads the archive, builds indexed in-memory state, validates the change, appends events, and atomically rewrites the archive.

Output

JSON is the default output and is intended for agents:

{
  "ok": true,
  "command": "note",
  "generated_at": "2026-05-13T10:00:00+00:00",
  "ids": {},
  "data": {},
  "warnings": []
}

JSON records include stable RFC3339 created_at and updated_at fields. Use --human for interactive summaries with local-device timestamps rendered as readable wall-clock time:

sillok --human day

Command Reference

Global options:

sillok --store /path/to/sillok.slk.zst <command>
sillok --human <command>
sillok --json <command>
sillok --at 2026-05-13T10:00:00Z <command>
sillok --tz America/Denver <command>

Initialize the archive if absent:

sillok init

Record a task or work note. Notes default to completed; use --status for open, active, blocked, or completed:

sillok note "Implemented timerange query indexing" --tags rust,sillok
sillok note "Investigating archive compaction" --status active --purpose "Reduce read latency"
sillok note "Split reducer from view indexing" --parent <record_id> --tags rust,indexing

Manage day objectives:

sillok objective add "Finish archive indexing"
sillok objective add "Finish archive indexing" --tags rust,storage
sillok objective complete <objective_id> --note "All scoped work is complete"

Amend current derived state:

sillok amend <record_id> --text "Corrected task text"
sillok amend <record_id> --status completed
sillok amend <record_id> --purpose "Clarify why this work mattered"
sillok amend <record_id> --tags rust,indexing

Retract a task or objective from current views:

sillok retract <record_id> --reason "Recorded against the wrong objective"

Read records:

sillok show <record_id>
sillok day
sillok day --date 2026-05-13
sillok query --from 2026-05-13T00:00:00 --to 2026-05-13T23:59:59
sillok query --from 2026-05-13T00:00:00 --to 2026-05-13T23:59:59 --tag rust
sillok query --from 2026-05-13T00:00:00 --to 2026-05-13T23:59:59 --status completed
sillok query --from 2026-05-13T00:00:00 --to 2026-05-13T23:59:59 --context /home/cyh/project
sillok tree --root <record_id>
sillok tree --date 2026-05-13

Validate and export:

sillok doctor
sillok export json
sillok export json --from 2026-05-13T00:00:00 --to 2026-05-13T23:59:59

Reset the archive only when an operator explicitly asks for a full reset. This creates a timestamped backup first:

sillok truncate --yes

Backfill with explicit timestamps and timezone attribution:

sillok --tz Asia/Seoul --at 2026-05-13T21:30:00 note "Backfilled a late task"
sillok --at 2026-05-13T21:30:00+09:00 note "Backfilled a Seoul-time task"

Agent Integration

Add a short Sillok section to a repository AGENTS.md so coding agents record objectives and completed work while they operate:

## Sillok

Use Sillok for substantive agentic work. Record objectives, completed tasks,
and corrections during the session instead of relying on chat history. JSON is
the default output for agents; use `--human` only for summaries intended for a
person. Never run `sillok truncate --yes` unless the user explicitly asks to
reset the whole archive.

```bash
sillok objective add "Ship the storage/indexing refactor"
sillok note "Split reducer from view indexing" --parent <objective_id> --tags rust,sillok
sillok amend <record_id> --status completed
sillok note "Fixed relink regression coverage" --parent <objective_id> --tags tests
sillok show <record_id>
sillok query --from 2026-05-13T00:00:00 --to 2026-05-13T23:59:59 --tag rust
sillok objective complete <objective_id> --note "Scoped work is complete"
sillok day --human
```

Use `--at` for backfilled work and `--tz` when day attribution matters:

```bash
sillok --tz America/Denver --at 2026-05-13T16:45:00 note "Backfilled release notes" --tags docs
```

Development

Run checks:

cargo fmt
cargo clippy --all-targets --all-features
cargo test

Project constraints:

• No unwrap() or expect() in project source or tests.
• Keep modules under 300 lines where practical.
• Keep folder mod.rs files to module declarations only.
• Prefer explicit error handling and structured tracing.
• Do not treat the serialized archive as a public standard; optimize the in-memory representation and CLI behavior first.

Design Notes

See docs/plan/sillok-cli-chronicle-design.md for the initial implementation plan and data model notes.