Rekall context, anchored
GitHub vmcforge
/rk project:ledger the project, and every task on it task:fix-vat-rounding the task, its description, its wrapup, its notes

one call returns 1 project 1 task 3 steps 2 notes 1 wrapup 2 commits

Start every Claude Code session where the last one stopped.

Rekall keeps the context code alone cannot hold: why a task exists, what you already decided, where work paused and what it cost. It runs locally, and the line above is enough to load it.

Source on GitHub See the console

why rekall

Code alone cannot tell you why a task exists or where the last session stopped.

A coding agent can read your files and understand the code. It cannot see the brief, the decisions you already made, or where the work paused. Rekall stores that context and gives each part a stable name.

  1. Name it: task:fix-vat-rounding

    Each anchor resolves to one record. No searching, and no re-explaining the task in every new prompt.

  2. Load it: one call

    The call returns the brief, linked notes, selected commits and related records. A session starts from decisions you already made.

  3. Write it back: wrapup and step:N done

    Claude updates the implementation state and moves the checklist as it works. The next session, or a teammate, reads that state instead of a chat transcript.

Everything stays on your machine: one SQLite file in a folder you choose, no account, no uploads.

the console

One console, three panes.

Tasks are on the left, grouped by project. The task dossier is in the middle, in the same order /rk returns it. The note you are reading or writing is on the right.

The top bar holds the /rk field, your Claude usage, the run queue and the count of claimed work waiting for review. Each numbered marker opens the part of the app it points to.

demo data Press a number on the screen, or here:

new in 0.4.0

What's new in 0.4.0, shown on one team's billing project.

Seven features: Claude resources, skills, components, sections, flows, token tracking and diagrams. Every example uses Northwind's billing backend, project ledger.

Claude resources

Stop repeating the same Claude setup across projects.

Every project grows its own memory under ~/.claude. After a while, the same lesson appears in several places, and it is unclear whether a skill already covers it.

Rekall shows the full library in one view and compares memories side by side. When it finds overlap, it suggests where to keep it once:

  • Add to CLAUDE.md when it is short and universal, such as a one-line testing rule.
  • Make a skill when it is long or procedural, such as a release flow Claude should load only when needed.
  • Probably already covered when a skill or CLAUDE.md already matches most of that memory, so you can verify and remove duplicates.

The review is text-based, not semantic: it catches restatements and can miss paraphrases. It only suggests; files never change automatically.

exampleWhen two projects repeat the same testing rule or release process, Rekall shows where it should live once.

Skills on tasks and steps

Attach the right skills to tasks so no one has to remember the prompt.

A hotfix should follow your Rust standards. A UI review should use the design skill. Without structure, that depends on someone remembering to ask in the prompt.

Assign skills from your catalogue to a task, a tag, or a single step. Context started with Run here tells a session to load them before work begins. A step-level skill applies only while that step runs, and each step shows a badge with the number of skills that apply.

exampleThe Hotfix tag applies rust-standards to every task that uses it. Step 3 adds a design skill only for itself.

Components

Link a task to the services it touches, even across repositories.

In microservice systems, one feature often spans multiple repositories. A task that says “move the rounding out of billing, keep the rates in tax” otherwise makes the session guess which repos you mean, or makes you paste paths every time.

Declare each service once on the project: name, folder and a short ownership note. Write [[Billing service]] and [[Tax service]] in a task or step, and the session gets both folders and descriptions at first mention.

  • A folder can be any local path, so one task can link services from different repositories.
  • A missing name shows as a red struck-through chip in the console and as component not found to the session. Nothing is guessed.
  • Only the console can edit components, so a session cannot redefine your architecture.

exampleThree services are declared, each in its own repository. Invoicing is not one of them, and both you and the session are told.

Project sections

Write shared project knowledge once, then load it only when needed.

Deployment rules, conventions and a glossary apply to the whole project. Put them in a task and every session loads them whether needed or not. Keep them in your head and every session asks again.

A section is a titled project page outside task context, so it costs no tokens by default. A session reads the list of titles and opens only what the work needs. It can also draft one from a step, such as document the release process in a section named Deployment.

exampleDeployment, Conventions and Glossary live as project pages. They are listed, not auto-loaded.

Flows

Run delivery loops automatically: each outcome chooses the next step.

Implement, build, deploy, run end-to-end tests. When the build breaks, you go back to code; when tests fail, you go back again. A flat checklist stops after every step and waits for you.

Draw the steps as a graph and name routes by outcome: build-error back to implementation, deploy-error back to build, tests-failed back to implementation. The session claims each step with its outcome, and Rekall opens the next one automatically.

  • Nothing to tick between steps. You review the claimed work once the flow ends.
  • Every entry into a step is recorded, so you can see how many laps a loop took.

exampleMove 8: the build failed once and deploy failed once. Each branch went back to the step that could fix it.

Token counter

See exactly which project, task and step consumed your plan.

Without a count, an expensive task looks like any other until the usage meter is empty.

Rekall reads Claude Code transcripts and attributes every model call to the task or step active at that moment. Each step, task and project shows its token total with a day-by-day trend. The tooltip also breaks out input and cache tokens.

  • Sessions count wherever they ran, not only the ones opened from Rekall.
  • Calls made before the first /rk are not Rekall work and are not counted.

exampleIf one step takes 65% of a task's tokens, that is the step to split or describe better.

Diagrams

Ask how the code works and get a map linked back to source.

A hand-drawn diagram is often outdated by the next merge, and one with no source links cannot be verified.

Ask a concrete question, for example how an invoice gets its VAT. A session reads the code, generates Mermaid diagrams (sequence, state, ER), and links each element to implementation lines. Rekall rejects diagrams whose links do not resolve in the project folder. In the console, clicking a message opens its source and the calls under it.

exampleClick a message to open the lines that implement it and the calls under it.

a task at work

A task has an ordered checklist, and sessions work it live.

The description says why the task exists, and the wrapup says what the code does now. The checklist shows what is left, and the first open step is where the next session starts.

A session moves a step from open to running to claimed, and you see it live. The final state, done, is your tick after review. Claude can move a step forward but can never close it.

demo data Press a number on the screen, or here:

the project page

A project points to one folder, and task sessions run there.

Run here and Open in terminal start Claude Code in that folder, and Log commit reads its git history.

demo data Press a number on the screen, or here:

running it

Rekall runs locally, backed by a local file.

No server to host and no account to create. Download it, open it, register it once with Claude Code.

Download Rekall

Choose your OS. Each link resolves to the latest tagged release.

macOS macOS 13+ · Apple Silicon
Download the disk image
Linux x86-64 · server binary
Download the binary
Windows x86-64 · server binary
Download the binary

All builds and versioned releases →

First launch on macOS

The bundle is signed ad hoc and is not notarized. macOS quarantines a disk image downloaded with a browser and reports it as damaged. Clear the quarantine once:

xattr -dr com.apple.quarantine /Applications/Rekall.app
1 Search · the console, 1 of 5

One field searches across every task.

Type a word to search titles, labels, and the text of descriptions, steps, wrapups, and notes. Each result names its task and shows the words around the match.

Use ↑ ↓ to choose a result, then ↵ to open the pane that contains that text.

2 Filing a note · the console, 2 of 5

File a note by walking company, then project, then task.

Attach a note to the tasks it applies to by walking company, project, then task. The strip at the top lists every attached task, and it is the only place you edit that list.

Finished tasks stay hidden until you pick All, so the right task is usually one click away.

3 Tags · the console, 3 of 5

Tags classify tasks, and skills can ride on them.

A tag classifies a task and appears next to its title everywhere. It is also the right home for skills shared by one kind of task: assign rust-standards to Hotfix and every hotfix task carries it.

4 Run queue · the console, 4 of 5

The run queue works through tasks while you are away.

The queue processes tasks while you are away. Each task gets its own terminal; the session works open steps in order, claims each one, then starts the next task.

Add tasks by title or anchor, then choose Start now or schedule with At a time. A usage ceiling stops new work before your plan runs out, and the queue waits for the window to reset.

Open it from the dial next to the usage meter, or with q.

5 Settings and backups · the console, 5 of 5

Settings holds database, Claude Code, backups and notifications.

Settings includes the database folder, Claude Code options, backups, and notifications. Put the database in a synced folder to share it across machines, and open it on one machine at a time.

Rekall backs up at startup and every 24 hours, keeping the newest 10. Restore first backs up the current file, then replaces the database.

1 Drafts and planning · a task at work, 1 of 6

New steps start as drafts, and Claude can draft them for you.

Every new step starts as a draft: it waits on a shelf, does not count as work left, and no session can start it. Promote moves it onto the checklist.

/rk … plan asks a session to read the task and the code, then propose checklist items as drafts. It builds nothing, and a second plan adds only what the first one missed.

A task with no steps. Plan here appears only while a terminal is open on the task.

a session planning the task

> /rk project:ledger task:late-payment-reminders plan

✓ rekall_context · 1 project · 1 task · 0 steps · 0 notes

… read the reminder module and the billing component.

✓ rekall_propose_step · "Find the invoices that are 7 days late"

✓ rekall_propose_step · "Send the first reminder"

✓ rekall_propose_step · "Send the second reminder after 14 days"

Proposed 3 drafts. Left out the dunning letters:

the description puts them out of scope.

what a session sees of the drafts

> /rk project:ledger task:fix-vat-rounding

<steps done="1" open="1" awaiting-review="1" draft="2">

- [x] Reproduce the one-cent drift with a failing test

- [ ] Round per line, not per invoice (claimed, awaiting review)

- [ ] Review the invoice PDF layout

<!-- 2 further steps still in draft, not shown -->

</steps>
2 Run here · a task at work, 2 of 6

Run here opens a real Claude Code terminal in the console.

Run here starts real Claude Code in a console terminal, in the project's folder, and types /rk with the task anchor. It is the same claude binary your own terminal runs.

Open in terminal opens the same session in iTerm2 or Terminal.app. The dock at bottom right counts running timers and live terminals and jumps to either.

3 The seal · a task at work, 3 of 6

Each step has a seal, and the seal shows its state.

Each step has one small seal showing its state: open, running, claimed or done. Only a running step moves, so the active step stands out in a long checklist.

Point at a card to see what a click would do.

4 Claim and review · a task at work, 4 of 6

A session claims a step, and you can accept it or send it back.

Open a claimed step to review it. Accept marks it done, while Send back reopens it for the next session. The top-bar count lists every claimed step waiting for you.

A session receives open and running steps in full, and finished ones by title only, so completed work is not rebuilt.

working one step of the checklist

> /rk project:ledger task:fix-vat-rounding step:2 start

✓ rekall_step · step 2 is running

… the VAT column now carries the sum of rounded lines.

> /rk project:ledger task:fix-vat-rounding wrapup

✓ rekall_wrapup · folded the running step into the state, replaced in place

> /rk project:ledger task:fix-vat-rounding step:2 done

✓ rekall_step · step 2 is claimed, waiting for the console

step:N done marks the step claimed. The done tick is yours.
5 Commits · a task at work, 5 of 6

Log a commit to a task or step, and Rekall keeps its diff.

Log commit stores the project folder's tip against a task or step, including subject and diff. The caret opens the last 30 commits if you need an older one, and a session can log its own with rekall_record_commit.

Mark a commit as add to context and the next /rk includes its diff, so the session sees exactly what changed. Only you can set that flag.

a session logging what it just committed

> git commit -m "fix: round VAT per line and sum the lines"

[main 3b0c4e1] fix: round VAT per line and sum the lines

✓ rekall_record_commit · project:ledger task:fix-vat-rounding step:2

Logged `3b0c4e1` - fix: round VAT per line and sum the lines

- against "Round per line, not per invoice".

The hash and the subject came from the repository, not from the session.

the context of a task with two commits chosen

> /rk project:ledger task:fix-vat-rounding

✓ rekall_context · 1 project · 1 task · 3 steps · 2 notes · 2 commits

<commits count="2">

<commit hash="3b0c4e1…" step="Round per line, not per invoice">

fix: round VAT per line and sum the lines

@@ -3,6 +3,12 @@ pub fn vat_for(line: &Line, rate_percent: u32) -> i64 {

- vat_of_invoice_total(lines)

+ lines.iter().map(|line| vat_for(line, rate)).sum()

</commit>

</commits>
6 Wrapup and history · a task at work, 6 of 6

Every task has one wrapup, and each save replaces it completely.

A wrapup explains what the implementation does now for someone who was not in the session. It is not a changelog. Each save replaces the whole text, and any step ticked after the last wrapup is flagged so the next one includes it.

History keeps earlier versions, newest first, and a restore can be undone the same way. Sessions never read history.

closing a session

> /rk project:ledger task:fix-vat-rounding wrapup

✓ rekall_wrapup · 1,486 characters, replaced in place

! the version replaced had been edited by hand, 2 days ago

Wrote what vat_total does now, with the step closed since

the last wrapup and the one thing still open.
1 Commit on claim · the project page, 1 of 2

A project can auto-commit when a step is claimed.

Commit on claim is a switch on the project page. When on, claiming a step commits the folder and logs that commit on the step, with a Conventional Commits message generated by the session.

It works only when the folder is a git repository. A clean tree creates no commit, and if git refuses, the claim still counts.

a claim that commits

> /rk project:ledger task:fix-vat-rounding step:2 done

✓ rekall_step · step 2 is claimed · committed 3b0c4e1 on main, logged against step 2

> git log -1

commit 3b0c4e1

fix: round VAT per line and sum the lines

An invoice with many small lines no longer drifts by a cent: each line's

VAT is rounded in cents first and the invoice VAT is the sum of them.

The failing test from step 1 now passes.

Refs: project:ledger task:fix-vat-rounding, step 2
2 Report · the project page, 2 of 2

The report groups tracked time by company, project and task.

The report groups recorded time by company, project and task for a week or a month. Each task opens on the steps it closed in that period, so invoice lines still name the work.

Copy as markdown puts the report on your clipboard with anchors and closed steps.