Write one claim. Search it back.

ljos gives coding agents a memory, a work tracker, and a check on every shell command. Claude Code and Codex are such agents, as are opencode and agy. Cursor is one too. It writes one claim when you say Remember: or Prefer:, then searches that claim back. Nothing is mined from chat, and memory stays on your machine unless you turn on a remote judge.

Write one claim How sitting works Source

Fig. 1 A sitting, in the order ljos prints it. The ticket stays open until vissue closes it.

specimen

$ ljos sitting demo-k29f --verbose
== doctor
== cards
== due
== island
== blockers
== playbook
== recall
== timeline
== reclaim
== claim
gen=2

install

curl -fsSLO https://github.com/leidarljos/ljos/releases/latest/download/install.sh && sh install.sh
ljos remember "the default fuse is CombMNZ"
ljos search fuse

ljos remember starts the writer when none is answering. The walk: First write. The name: leiðarljós.

Why this exists

Agents forget, remember the wrong things, and run any command.

They forget

Each session starts cold. The fix you agreed on yesterday, the rule about force pushes, the reason a test is skipped: gone unless someone pastes it back in.

Auto-memory fills with things nobody said

Tools that mine the transcript keep whatever a model guessed was worth keeping, including text that came from a web page or a tool result. That is how memory gets poisoned.

Shell commands run unchecked

A coding agent with a shell can push, delete, or pipe a download into sh on its own judgement.

ljos writes a memory only when you say Remember: or Prefer:, keeps it in plain local files you can read, and checks each shell command against fixed rules before it runs. No model sits in the write path or the check, and it all runs on a CPU.

The loop

Sit, work, finish.

Fig. 2 The sitting loop and the five stores it reads and writes. Every store is a local file or a loopback service.

01
Sit

ljos sitting ID opens the ticket: doctor, sync, cards, due, island, blockers, playbook, recall, timeline, then the claim. It refuses a ticket with open blockers.
02
Work

ljos note logs progress on the ticket. deedar create records what the work produced, and ljos deed cites it. ljos remember and ljos prefer are the only memory writes.
03
Finish

ljos finish ID remembers the lesson, fires the island, completes the session node, and learns from an outcome when one is named. The ticket stays open until vissue closes it.

cards USER.md, MEMORY.md
What the human froze. ljos prints these two files and never writes them.
sit reads
pack packset
Lessons and preferences, one claim each, searched back per prompt.
sit reads · work and finish write
tracker vissue
Tickets as plain Org files in a git repository.
sit reads · work notes · finish completes
deeds deedar
A hashed record of each artefact the work produced.
work writes · the ticket cites
claims claimdag
One live claim per holder per ticket. A second claim on a held ticket is refused.
sit claims · finish completes

ljos words: a seat is one agent runner on one machine, with its memory and claims. A sitting is one piece of work on one ticket. A deed is a hashed record of what that work produced. packset is the memory store that search reads, and vissue is the tracker, plain Org files in git. leiðarljós is Icelandic for a guiding light.

Fig. 3 One sitting on a fresh seat, about a minute long. A script types the commands; every line of output is real. The script is demo.sh.

The recording needs JavaScript. The raw cast is ljos-demo.cast, playable with asciinema play.

Fig. 4 LongMemEval_S, n = 470 answerable questions, session retrieval. CombMNZ fuses BM25+ with multilingual-e5-large; the default install encodes with bge-small-en-v1.5, and without the encoder search stays lexical. Writes only on Remember: and Prefer:.

arm	recall@5	QA / ceiling
BM25+ lexical	0.914	—
CombMNZ fused	0.949	0.549 / 0.634

QA for CombMNZ fused uses a local 7 B reader and judge, top five sessions, against the labelled-session ceiling. Retrieval source: crates/packset-daemon/examples/longmemeval.rs in packset. Data held privately. Compare · packset explanation.

Fig. 5 Install cost of the same local stack, packset and ljos, built with cargo install from crates.io on one 8-thread Xeon with two build jobs. Lexical search, no encoder.

build, both crates: 4 min 20 s
binaries on disk: 45 MB
packsetd resident: 15 MB
search p50 / p95: 3.3 / 4.1 ms

281 claims in the pack, one process per query. Method, script and raw logs.

Contents

Each store has its own site.

This page teaches sitting. Those pages teach the crate. Org plus Sphinx, the same shape as vissue.