/rk project:vega the project, and every task on it task:report-builder the task, its description, its wrapup, its notes
one call returns 1 project 1 task 6 notes 1 wrapup
Rekall stores your companies, projects, tasks and their markdown notes on your machine. One anchored line loads a task, the project it belongs to and every note on it into a Claude Code session.
why anchors
The code does not record what a task is for or where the work stopped.
A coding agent reconstructs a project by reading its files, which gives it the code. The brief, the decisions already settled and the point the last session stopped at are not in there. Rekall stores those and addresses them by name.
The anchor is explicit
task:report-builder resolves to one record. There is no search step and no question in prose to answer before the work starts.
One call returns everything attached
An anchor returns the record, everything it references resolved in full with their notes, what references it back as anchors, and its own markdown.
The session writes the state back
wrapup at the end of the line has Claude record what the implementation now is. The next session opens on that instead of on inference.
Nothing leaves the machine
The database is an H2 file under ./data. There is no account to create and nothing is sent anywhere.
the console
The console is one screen with three panes.
The field at the top is always present and takes the same grammar as /rk. The left pane is the project you are scoped to. The middle pane keeps the description, the steps and the wrapup above the notes, in the order the three are asked in: the description is what the task is, the steps are what is left of it, the wrapup is what it became, and the notes are the background to all three.
- Report builder report-builder 6
- Retry policy on the ingest queue retry-policy 3
- Anchor parser: quoted values anchor-parser 2
- Invoice export invoice-export 4
- Schema migration 14 to 15 schema-migration 1
One report per week and per month, grouped by company, project and task, with the totals the invoice is written from.
Next: One query for the month frame
The builder reads a week or a month of sessions and groups them company, project, task. Totals are computed in ReportService and the view never sums anything.
1 step done since this was written
2 notes newer than this
- Mordecai cluster access 3 tasks · 6d ago shared
- Invoice line query, final shape 2h ago
- Why the totals are computed server side 1d ago
- PDF renderer: the three we tried 4d ago
- Naming convention for report columns 2 tasks · 9d ago shared
- Stakeholder call, 12 August 12d ago
One row per task per day, so a session that crosses midnight lands on the day it
started. The join to company is what the report groups on.
Why the totals are not computed in the view
Two screens were summing the same seconds with different rounding, and the invoice
disagreed with the calendar by eleven minutes over a month. The totals are computed
once, in ReportService, and every screen reads them.
- A session counts on the day it started.
- A running session counts up to now.
- Nothing on the report screen is typed in by hand.
mocked data The dot on a row is its status, the diamond says the task has a wrapup, and the number is how many notes are on it.
the grammar
An anchor is entity:value, and the value is the label.
The entities are company, project and task. A label is lowercase, has no spaces, and is unique inside its parent. The title is what the record is called, and changing it never moves the anchor.
| Form | Meaning |
|---|---|
/rk project:vega task:report-builder | The project and that task, both in full |
/rk project:vega | The project, plus its tasks as a list of anchors |
/rk vega report-builder | Positional. Works while each term matches exactly one record |
/rk task:"report builder" | Quote a value that contains spaces |
/rk project:vega task:report-builder wrapup | Write the task's wrapup instead of loading it |
A bare term with no entity is looked up across all three and accepted only when exactly one record matches. When more than one matches, the candidates come back and nothing is loaded.
> /rk report-builder
! two records match "report-builder", nothing loaded
project:vega task:report-builder Acme
project:atlas task:report-builder Northwind
Task labels are unique per project. Add project: to choose.
the steps
A task carries an ordered checklist of what is left.
The description says what a task is for and grows as the work is redefined. Neither it nor the wrapup says which parts are finished, and working that out by reading one against the other is slow by hand and a guess for a model. The checklist is a node on a line instead: the first step still open carries the ring, opens with its detail, and is what a session is for. A step is ticked here and nowhere else, by the person who reviewed the work, never by Claude.
- Report builder report-builder 6
- Retry policy on the ingest queue retry-policy 3
- Anchor parser: quoted values anchor-parser 2
- Invoice export invoice-export 4
- Schema migration 14 to 15 schema-migration 1
One report per week and per month, grouped by company, project and task, with the totals the invoice is written from.
Next: One query for the month frame
The builder reads a week or a month of sessions and groups them company, project, task. Totals are computed in ReportService and the view never sums anything.
1 step done since this was written
2 notes newer than this
- Mordecai cluster access 3 tasks · 6d ago shared
- Invoice line query, final shape 2h ago
- Why the totals are computed server side 1d ago
- PDF renderer: the three we tried 4d ago
- Naming convention for report columns 2 tasks · 9d ago shared
- Stakeholder call, 12 August 12d ago
Steps
Report builder
/rk project:vega task:report-builder copy3/5
Hide done
What is left, in order. Every /rk project:vega task:report-builder hands Claude the open ones in full
and the done ones by name alone.
- Group sessions by company, project and task
- Compute the totals once, in ReportService
- One column per day against the eight hour line
- One query for the month frameDetail write read
The month frame reuses the week query and issues thirty of them, one per day. Replace them with one range query over the sessions, bounded by the frame, and keep the grouping in ReportService where the totals already are.
The week frame must give the same totals before and after. The test on week 34 is the check.
- Copy as markdown with the day breakdown
mocked data Every /rk hands Claude the open steps with their detail in full, and the done ones by title alone, so finished work is never rebuilt.
the wrapup
Every task carries one wrapup, and it is replaced whole.
A wrapup is what the implementation currently is. It is not a changelog: no "added", no before and after, nothing dated. It describes the system as it stands, for a reader who was not in the session.
The cap is 20,000 characters, against 100,000 for a note. It is lower because a wrapup describes the current state, and a long one is usually a log of how it got there.
A step ticked after the wrapup was last written is work the text cannot mention. The
context marks it (finished since the wrapup was written) and hands its
detail back for that reason alone, so the next wrapup folds it in rather than starting
from memory of the session.
- Report builder report-builder 6
- Retry policy on the ingest queue retry-policy 3
- Anchor parser: quoted values anchor-parser 2
- Invoice export invoice-export 4
- Schema migration 14 to 15 schema-migration 1
One report per week and per month, grouped by company, project and task, with the totals the invoice is written from.
Next: One query for the month frame
ReportService groups a week or a month of sessions and computes every total once. ReportRidge draws one column per day against the eight hour line. Two steps are open.
- Mordecai cluster access 3 tasks · 6d ago shared
- Invoice line query, final shape 2h ago
- Why the totals are computed server side 1d ago
- PDF renderer: the three we tried 4d ago
- Naming convention for report columns 2 tasks · 9d ago shared
- Stakeholder call, 12 August 12d ago
What the report builder currently is
ReportService groups a week or a month of sessions by company, project and
task, and computes every total once. ReportRidge draws one column per day
against the eight hour line, and each task's row carries the steps it closed in the
period.
Settled
- A session counts on the day it started, including one that crosses midnight.
- A running session counts up to now.
- Company colour is derived from its id, so a new company never recolours the chart.
- A closed step is dated by when it was ticked, not by the row it appears on.
Open
- The month frame reuses the week query and issues thirty of them.
- Copy as markdown emits anchors but not the day breakdown.
mocked data The pane says who wrote what is on screen and how long ago. Correcting it by hand is allowed, and the next wrapup call says when the words it replaced were yours.
> /rk project:vega task:report-builder wrapup
✓ rekall_wrapup · 1,486 characters, replaced in place
! the version replaced had been edited by hand, 2 days ago
Wrote what ReportService and ReportRidge now do, folded in the
step closed since the last wrapup, and the two things still open.
It replaced what was there.
the model
A note belongs to every task it applies to.
Cluster access or a naming convention is written once and arrives with each task that references it. Deleting a task unlinks its notes and removes only the ones left on nothing. A wrapup belongs to exactly one task, and the database enforces that.
Company
company:acme- name
- description
- its projects
Project
project:vega- label, unique per company
- title, status, description
- its tasks
Task
task:report-builder- label, unique per project
- description, status
- an ordered checklist of steps
- one wrapup
- its notes
Document
no anchor of its own- title, kind
- markdown body
- the tasks it is on
Adding an entity means a JPA class and a Liquibase changeset. The schema is fixed at compile time and the interface cannot change it.
report
The report groups recorded time by company, project and task.
The frame is a week or a month. Under the total there is one column per day, stacked in each company's colour and measured against a dashed line at eight hours. Below that, each company gets a section listing its projects, its tasks and the total for each.
Under an hours row are the steps that task closed in the period, oldest first, the count sitting on the control that opens them: hours say how long the work took, steps say what came out of it. A step ticked before or after the frame is counted in the line underneath and not listed, since a report naming it would claim work in a week it did not happen in.
Nothing on this screen is typed in. It regroups the sessions the timer recorded and the steps ticked while they ran.
Tracked this week
33h 50m
5 tasks, 2 companies · 5 steps closed · 9h 20m on the busiest day
- M
- T
- W
- T
- F
- S
- S
- 3 Report builder project:vega task:report-builder 11h 20m
- Group sessions by company, project and task Mon 18
- Compute the totals once, in ReportService Tue 19
- One column per day against the eight hour line Wed 20
2 steps still open
- 1 Retry policy on the ingest queue project:vega task:retry-policy 7h 45m
- Exponential backoff with jitter on the consumer Tue 19
3 steps still open
- 0 Invoice export project:vega task:invoice-export 5h 25m
Nothing closed this week · 4 done outside this period
- 1 Tenant provisioning project:atlas task:tenant-provisioning 5h 50m
- One schema per tenant, created on first login Thu 21
1 step still open
- Audit log retention project:atlas task:audit-log-retention 3h 30m
mocked data Copy as markdown puts the report on the clipboard with the anchors and the closed steps intact, so a line in an invoice still names the task and the work it came from.
export
The archive is a folder tree, one markdown file per note.
The export is a backup. Nothing reads it back. A note attached to several tasks is written under each of them, and MANIFEST.md lists those copies so a reader knows they are the same note.
Acme/
vega/
report-builder/
WRAPUP.md what the task currently is
DESCRIPTION.md
invoice-line-query.md
mordecai.md
retry-policy/
mordecai.md the same note, under each task it is on
Northwind/
atlas/
tenant-provisioning/
DESCRIPTION.md
MANIFEST.md statuses and anchors for everything above Download it with curl -OJ http://localhost:47355/api/export, or with
the Export button in the top bar.
settings
Settings holds the database folder and the Claude Code registration.
The database is a file in a folder you choose, and Rekall remembers every folder it has been pointed at. Switching between them restarts the server and reopens on the other one. A folder that is no longer on disk is marked as unreachable rather than dropped from the list.
The folder can be a synced one. Pointing it at OneDrive, iCloud Drive or Dropbox gives the same notes on more than one machine. The database stays a single H2 file, so only one machine should have it open at a time. Two machines writing to it at once can corrupt the file.
Database
- Local rename In use ~/Projects/rekall/data
- Shared rename ~/Library/CloudStorage/OneDrive-Personal/rekall Switch Forget
- Old laptop rename Unreachable /Volumes/backup/rekall Forget
+ Add another database
A database already lives here. It will be opened as is.
Open this databaseClaude Code
--dangerously-skip-permissions to what Open in Claude Code
launches. That session edits, runs and deletes without asking first.
Sessions already open keep the configuration they started with. This one needs restarting.
mocked data The field checks the path as you type and says what will happen to it before anything commits: a database already there is opened as is, an empty folder gets a new one, and a folder that does not exist is refused. Rekall never creates the folder itself.
The registration is one button
It writes the MCP registration for every folder and installs the /rk command. The same button repairs a registration pointing at the wrong port, an older copy of the command, or one folder that kept a setup of its own and wins inside it. The badge says which of those it found.
Sessions already open keep what they started with
A session picks up the registration when it starts, so one that was already running has to be restarted before /rk resolves.
The permissions switch
It adds --dangerously-skip-permissions to what Open in Claude Code
launches, so that session edits, runs and deletes without asking. It is
off until you turn it on, it appears only in the application window, and
the setting stays on that machine rather than in the database.
running it
Rekall runs as one process against a local file.
There is no database server, no container and no cluster. The port is 47355 and not 8080, because the MCP endpoint is a fixed URL registered with Claude Code, and a port clash breaks that registration instead of moving the server.
This image is rebuilt on every commit to main, so it changes without notice. The bundle is signed ad hoc and is not notarized. A disk image downloaded through a browser is quarantined, and macOS reports it as damaged rather than unsigned. Clear the quarantine once:
xattr -dr com.apple.quarantine /Applications/Rekall.app
From a terminal
make run compiles the frontend and starts on
localhost:47355. The MCP endpoint is /mcp on the same port.
make mcp-add registers the server with --scope user. Without
that flag the registration applies only to the folder the command was run
from.
As a macOS application
The disk image above is the dmg-jvm flavour: a bundled Java runtime and
the jar. It reaches the first screen in about three seconds. make
dmg-native builds the other flavour locally, a GraalVM binary that
opens in under a second, and needs GraalVM as JAVA_HOME.
It uses the same port, the same config file and the same MCP endpoint as the terminal. An application started while a terminal instance is running attaches to it instead of starting a second server.
Opening a session
One button on a task or a project opens a terminal in that project's folder with /rk already running. The anchor is never copied, pasted or typed by hand.
This works only inside the application. A browser tab cannot open a terminal, and an endpoint that allowed it could be called by any other page open in that browser.
| Tool | Version | Used for |
|---|---|---|
| Java | 25 | Backend, domain and the MCP server |
| Maven | 3.9+ | Build and tests |
| Node | 22+ | Vite build of the frontend |
| pnpm | 9+ | Frontend dependencies |
The MCP server exposes two tools.
rekall_context reads. rekall_wrapup replaces the wrapup of one
task. There is no query tool and no schema tool: an anchor names the record
directly, and a question asked in prose fails silently when the guess is
wrong.
/rk project:vega task:report-builder