Memory To Thrum Pointer

---
name: memory-to-thrum-pointer
description:
  "Use when MEMORY.md is near or over its read limit, or when adding a new
  memory entry. Moves an entry's full text into a thrum memory record and
  shrinks its index line to a trigger plus the thrum memory ID, with a
  byte-for-byte check."
# source: claude-plugin/skills/memory-to-thrum-pointer/SKILL.md
---

## Memory to thrum pointer

### Why

An index line that restates a rule goes wrong when it is shortened, because
shortening drops the scope that makes the rule true. An index line written as a
TRIGGER cannot contradict the rule, because it does not state the rule. It only
tells you when to read the full text.

So each entry has three parts:

- **Full text:** the topic file's body, copied unchanged into a thrum memory
  record (`--full`). This is the source to read before acting.
- **Trigger:** one line saying WHEN it applies, never WHAT it says. It goes in
  the record's `--oneline` field and in the index.
- **Topic file:** kept as the local copy. Never delete it.

Index line format, under ~140 characters:

```text
- 🔴 <trigger: when this applies> → `thrum-mem-<ID>`
```

The topic file carries `thrum_memory: <ID>` in its frontmatter; find it with
`grep -l 'thrum_memory: <ID>' <memory dir>/*.md`.

Keep the 🔴 only on entries that already have it.

### Writing the trigger

Name the situation or action that should make you read the rule, for example
"before choosing a model for any role" or "when the email bridge decides which
inbound mail it processes". Do not put the rule's answer in the trigger: no
"always", "never", "X not Y" or numbers. If the answer leaks in, it will drift
from the full text.

Test it by asking: if I were about to take the wrong action, would this line
make me stop and read? If not, name the action more concretely.

### Steps for one entry

Use the helper for steps 1 to 5. Run it from any directory with
`THRUM_REPO=<repo>` set to the thrum repo root (the helper runs thrum from
there). It extracts the body, creates or reuses the record, checks it byte for
byte, writes `thrum_memory` into the frontmatter, and prints the ID. It exits
non-zero on any problem, and then you leave that index line alone.

```bash
bash <skill-dir>/resources/to-thrum.sh <topic-file.md> "<trigger>" [agent_rule|lesson]
```

Then do step 6 by hand. The manual steps below are what the helper does.

1. Read the topic file. Its body (everything after the frontmatter) is the full
   text.
2. Check whether a thrum memory already holds that text. Search with
   `thrum memory search` on a distinctive phrase. If the topic file names a
   `thrum-mem-` ID, `thrum memory show <ID> --format body --zoom full` and
   compare.
3. If there is none, create one. Write the body to a scratch file first, then
   pass it with `@file`, so the shell never rewrites it:

   ```bash
   thrum memory create --kind agent_rule --scope agent \
     --title "<topic file name>" --oneline "<trigger>" \
     --full @"$SCRATCH/body.md" --tag claude-memory --json
   ```

   Use `--kind lesson` for a habit or lesson rather than a rule.

4. Verify byte for byte before touching the index:

   ```bash
   thrum memory show <ID> --format body --zoom full > "$SCRATCH/back.md"
   cmp "$SCRATCH/body.md" "$SCRATCH/back.md"
   ```

   If they differ only by a trailing newline, that is acceptable; note it. Any
   other difference: stop and do not change that index line.

5. Add `thrum_memory: <ID>` to the topic file's frontmatter `metadata`.
6. Replace that entry's text in MEMORY.md with the trigger-format line. Change
   only that one entry. Entries packed on one line with `·` are separate
   entries: move only the one you are converting and leave its neighbours as
   they are.

### Rules

- Never delete a topic file, a thrum memory or an index entry. This skill only
  adds records and shortens lines.
- Never merge two entries into one line or one record.
- Never reword the full text. It is copied exactly.
- Do not convert the FORMAT CONTRACT header or the hook warning at the top of
  MEMORY.md. They must stay in full in the index, because they guard against
  editing the index wrongly.
- thrum memories are local to this machine. Do not convert an entry another box
  has to read.
- After a batch, reload MEMORY.md and check its size is below 24.4KB, then
  re-read three converted entries' full text through the ID to confirm they come
  back.

### Using converted entries

When a trigger matches what you are about to do, read the full rule before
acting. The trigger is not the rule. The exact command, run from the thrum repo
(thrum finds its daemon from the current directory, and the memory folder is not
a repo):

```bash
cd <repo> && thrum memory show <ID> --format body --zoom full
```

If thrum is unreachable, find the topic file by its ID (grep above) and read it:
it holds the same text.

The index header carries this command once, near the top. Do not repeat it on
each index line; one copy at the top is always in view and costs a fraction of
the space.

### Other runtimes (survey 2026-10-21, agents' own reports, mostly not measured)

The pattern works on every runtime. What changes is where the index lives and
where the skill is installed. In every case, spell out the read command with
`cd <repo> &&`: no runtime resolves an ID by itself, and shells may be fresh
subshells.

| Runtime     | Where the trigger index goes (always loaded)        | Skill location                                    | Limits                                                                                                                                                    |
| ----------- | --------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code | `~/.claude/projects/<slug>/memory/MEMORY.md`        | `~/.claude/skills/`                               | 24.4KB index read limit                                                                                                                                   |
| Codex       | AGENTS.md chain                                     | `~/.agents/skills/`                               | ~32KiB `project_doc_max_bytes`; MEMORY.md not read                                                                                                        |
| OpenCode    | AGENTS.md / CLAUDE.md (loaded in full)              | `~/.config/opencode/skills/` or `.claude/skills/` | skill description always loaded: keep it short                                                                                                            |
| Muse        | its own MEMORY.md (native read_memory)              | already sees `~/.claude/skills/`                  | no cutoff at 40KB (measured 2026-10-21, 401 lines); higher untested. Prefers its own topic files; use thrum IDs only for rules shared with other runtimes |
| Cursor      | `.cursor/rules/<name>.mdc` with `alwaysApply: true` | `.cursor/skills/`                                 | always-apply text loads in full, so this saves the most                                                                                                   |
| Copilot     | AGENTS.md or the Copilot plugin                     | `~/.copilot/installed-plugins/`                   | ~41KB output cap on prime                                                                                                                                 |
| AGY         | AGENTS.md / GEMINI.md / `.agents/rules/`            | `.agents/skills/`                                 | 24KB per file, 20k-token rules budget; tool is `run_command`                                                                                              |

Each box needs its own installed copy in its runtime's skill location, and thrum
memory IDs are local to each box's daemon.

### Licensing

`thrum memory create` needs the memory.substrate entitlement. The helper checks
it through the daemon: a `thrum memory edit` on a probe ID returns "not found"
only when the entitlement is granted, because the gate runs before the lookup
and nothing is written. The check does not look at the license tier, so any tier
that the server grants the feature to proceeds. Without the entitlement the
helper prints "needs Thrum Pro (free for eligible public repositories)", exits
7, and changes nothing: no record and no index change.

### Improving this skill

If a trigger fails to stop a wrong action, or a step here is unclear, fix this
file in the same turn and note what changed.