How do I install the Mental Model Jotting skill?

Run npx skillmds@latest add delorenj/mental-model-jotting in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Mental Model Jotting safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Mental Model Jotting?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Mental Model Jotting free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Mental Model Jotting?

delorenj (@delorenj) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Mental Model Jotting by delorenj — Agent Skill

Name: Mental Model Jotting
Rating: 4.2 (5 reviews)
Author: delorenj

Mental Model Jotting

Capture durable mental-model memories during a work session with the `jot` command, so the session-end hook can flush them into question-framed Hindsight memories. Use whenever you learn something worth remembering — a gotcha, a non-obvious decision, negative knowledge ("X did NOT work"), a surprising discovery, or a "future-me will ask this" fact — and you want it to survive past this session. Triggers:"remember this, "jot that down", "capture this", "note for later", "save this insight", mental model, write-ahead memory, hindsight capture.

delorenj Updated Sep 10, 2026 1 repo stars

File contents

Mental-Model Jotting

A write-ahead log for memory. The moment you hit something worth remembering, run jot. At session end a hook hands your jots to a cheap model that question-frames, dedups, and retains them into Hindsight. You make the significance judgement (the expensive part, and only you have the reasoning); the flush does the mechanical polishing for free.

The one command

jot "whatever you just learned, phrased however — one line"

That's it. Append as many as you want during the session; each is one line. Don't polish wording — the flush rewrites each into a question-framed memory. Be specific: keep exact names, paths, ports, flags, commands, error strings. A vague jot produces a vague memory.

When to jot (the significance bar)

Jot when a fact would save a future engineer real time and is not obvious from the code:

Gotchas / footguns — "zellij 0.44 can't name a token at creation (clap bug); rename it in tokens.db after."
Non-obvious decisions + the why — "bind zellij to 0.0.0.0 not loopback because Traefik reaches the host via host.docker.internal."
Negative knowledge — "opencode run is too slow for hooks (>2min); call the model API directly." Prevents repeating a dead end.
Surprising discoveries — "hindsight hook scripts are hardlinked across ~/.agents and ~/.claude."
"Future-me will ask X" — anything you'd want to re-derive later. Phrase toward the question if it helps.

When NOT to jot

Trivia, one-offs, or anything obvious from reading the code.
Things already captured this session (the flush dedups, but don't spam).
Secrets/tokens — jot the shape ("token lives in $X"), never the value.

Prefer a few high-signal jots over many marginal ones. An empty jotfile is a fine outcome — the flush costs nothing when there's nothing to say.

How it flows (you don't manage any of this)

jot "…" → appends to ~/.agents/journal/jots/<cwd-hash>.md (worktrees isolate; override with $HINDSIGHT_JOTFILE).
Session ends → the Stop/session-end hook calls hindsight-jot-flush.sh.
It sends the jots to deepseek-v4-flash (direct HTTP), which emits MEM|<context>|<question-framed memory> lines, deduped against what was already retained this session.
Each is hindsight memory retain'd to the resolved bank; the jotfile is archived.

Because recall is semantic, not tag-based, memories are phrased to open with the question a future engineer would ask. You can jot in that shape too, but you don't have to.

Retain a fact right now (don't wait for session end): hindsight memory retain <bank> "<fact>" --context <cat> — see the hindsight skill.
The habit is reinforced by the question-framed-memories feedback memory loaded each session.

---name: mental-model-jottingdescription: Capture durable mental-model memories during a work session with the `jot` command, so the session-end hook can flush them into question-framed Hindsight memories. Use whenever you learn something worth remembering — a gotcha, a non-obvious decision, negative knowledge ("X did NOT work"), a surprising discovery, or a "future-me will ask this" fact — and you want it to survive past this session. Triggers:"remember this, "jot that down", "capture this", "note for later", "save this insight", mental model, write-ahead memory, hindsight capture.---# Mental-Model JottingA **write-ahead log for memory.** The moment you hit something worth remembering, run `jot`. At session end a hook hands your jots to a cheap model that question-frames, dedups, and retains them into Hindsight. You make the _significance judgement_ (the expensive part, and only you have the reasoning); the flush does the mechanical polishing for free.## The one command```bashjot "whatever you just learned, phrased however — one line"```That's it. Append as many as you want during the session; each is one line. Don't polish wording — the flush rewrites each into a question-framed memory. **Be specific**: keep exact names, paths, ports, flags, commands, error strings. A vague jot produces a vague memory.## When to jot (the significance bar)Jot when a fact would save a future engineer real time and is **not obvious from the code**:- **Gotchas / footguns** — "zellij 0.44 can't name a token at creation (clap bug); rename it in tokens.db after."- **Non-obvious decisions + the why** — "bind zellij to 0.0.0.0 not loopback because Traefik reaches the host via host.docker.internal."- **Negative knowledge** — "`opencode run` is too slow for hooks (>2min); call the model API directly." Prevents repeating a dead end.- **Surprising discoveries** — "hindsight hook scripts are hardlinked across ~/.agents and ~/.claude."- **"Future-me will ask X"** — anything you'd want to re-derive later. Phrase toward the question if it helps.## When NOT to jot- Trivia, one-offs, or anything obvious from reading the code.- Things already captured this session (the flush dedups, but don't spam).- Secrets/tokens — jot the _shape_ ("token lives in $X"), never the value.Prefer a few high-signal jots over many marginal ones. An empty jotfile is a fine outcome — the flush costs nothing when there's nothing to say.## How it flows (you don't manage any of this)1. `jot "…"` → appends to `~/.agents/journal/jots/<cwd-hash>.md` (worktrees isolate; override with `$HINDSIGHT_JOTFILE`).2. Session ends → the `Stop`/session-end hook calls `hindsight-jot-flush.sh`.3. It sends the jots to `deepseek-v4-flash` (direct HTTP), which emits `MEM|<context>|<question-framed memory>` lines, deduped against what was already retained this session.4. Each is `hindsight memory retain`'d to the resolved bank; the jotfile is archived.Because recall is **semantic, not tag-based**, memories are phrased to open with the question a future engineer would ask. You can jot in that shape too, but you don't have to.## Related- Retain a fact _right now_ (don't wait for session end): `hindsight memory retain <bank> "<fact>" --context <cat>` — see the `hindsight` skill.- The habit is reinforced by the `question-framed-memories` feedback memory loaded each session.

Frequently asked questions