---
name: pin
description: "Promote a specific insight, decision, or fact from the current conversation into one of the user's permanent context files (Profile, Projects, or Current State). Invoke whenever the user runs /pin or tells you to pin, remember permanently, or add something to their profile. Figures out which file the insight belongs in, updates it, and bumps the last_updated timestamp."
---

# pin — Promote Insight to Permanent Memory

Your job: take a specific insight, decision, or fact and write it into the right permanent context file in the user's Memcrate vault. This is the bridge from *session memory* (the Sessions folder) to *permanent memory* (`Profile.md` / `Projects.md` / `Current State.md`).

## Narrate before acting

**Before any tool call, output a one-line status message to the user** so they understand what's about to happen — especially the first time `/pin` runs in a fresh install, when each new tool triggers a permission prompt.

Open with something like:

> Pinning this — figuring out which context file it belongs in (Profile / Projects / Current State), then updating it.

After deciding the destination, restate which file you're about to edit before the Edit call.

## Vault Location

**Use Read and Glob, not Bash.** They produce clean permission prompts with full paths visible.

Try in order:

1. **Read `~/vault/Core/Context/Profile.md`** — the default install location. If Read returns content, `<vault>` = `~/vault`.
2. **Read `<cwd>/Core/Context/Profile.md`** — handles users who `cd`'d into their vault before launching Claude Code. Use the absolute working-directory path from your session context.
3. **Glob with `path: <home>` and `pattern: "*/Core/Context/Profile.md"`** — depth-1 scan of the user's home directory for vaults at custom paths like `~/myvault`. Resolve `<home>` from your session context (typically `/home/<user>` on Linux, `/Users/<user>` on macOS, `C:\Users\<user>` on Windows).
    - **One match** → `<vault>` is the first path segment of that match (strip `/Core/Context/Profile.md`).
    - **Multiple matches** → list them and ask the user which to use.

If all three fail, ask the user in plain English:

> I couldn't find a Memcrate vault at `~/vault`, in this directory, or anywhere one level deep in your home directory. Where is your vault? (Paste the absolute path. If you haven't set one up yet, run `memcrate init ~/vault` and try again.)

Then `Read <answer>/Core/Context/Profile.md` to confirm before proceeding.

The canonical context files always live at:

- `<vault>/Core/Context/Profile.md`
- `<vault>/Core/Context/Projects.md`
- `<vault>/Core/Context/Current State.md`

If they're not there, the vault is malformed — surface that to the user rather than writing to an alternate location.

## When to Use This

Session logs are ephemeral — they capture what happened in one conversation. Permanent context files hold things that should be true across *every* session. Examples of things worth pinning:

- "My core audience is junior developers" → `Core/Context/Profile.md`
- "Year-1 MRR target for my SaaS is $50K" → `Core/Context/Projects.md`
- "This week's #3 priority is shipping the auth rewrite" → `Core/Context/Current State.md`
- "I don't do live streams, talks, or podcasts" → `Core/Context/Profile.md` (anti-goals section)
- "New collaborator on a 2-month trial" → `Core/Context/Projects.md` (the relevant project's section)

Examples of things NOT to pin (these belong in `Core/Sessions/` via `/save`, not in the canonical files):

- "Today we decided the button should be blue"
- "The homepage copy is stuck"
- "I wrote 200 words of the book today"

The test: does this matter *next week*? If yes → pin. If it's only relevant to this session → save it via `/save` instead.

## Step 1: Identify the Insight

If the user says "pin this" after a specific statement, use that statement. If they say "/pin" without context, ask:

```
What specifically should I pin? Paste or describe the insight, decision, or fact you want moved into permanent memory.
```

## Step 2: Decide Which File

Use this decision tree:

- **`Core/Context/Profile.md`** — stable facts about the user, how they work, tools, preferences, goals, constraints, background. Changes quarterly.
- **`Core/Context/Projects.md`** — anything about a specific project (status, stack, equity, milestones, success markers, blockers). Changes monthly or on project events.
- **`Core/Context/Current State.md`** — this-week stuff (focus, deadlines, decisions log, open questions). Changes weekly.

If you're not sure, tell the user your guess and ask for confirmation:

```
This sounds like it belongs in **Core/Context/Profile.md** (Tools & Stack section). Does that match your thinking, or should it go elsewhere?
```

Let the user override. They know their own brain better than you do.

## Step 3: Find the Right Section

Within the target file, find the correct section. Examples:

- Tool change → `Core/Context/Profile.md` → `## Tools & Stack` section
- New project status → `Core/Context/Projects.md` → that project's block
- This week's priority → `Core/Context/Current State.md` → `## This Week's Focus` section
- New anti-goal → `Core/Context/Profile.md` → `## Anti-goals` (or wherever the user keeps them)
- New risk tolerance note → `Core/Context/Profile.md` → `## Personal Context` → Risk tolerance subsection

If the right section doesn't exist yet, ask the user whether to create it or where to put the content.

## Step 4: Write the Update

Use the Edit tool (not Write) to make surgical edits to the target file. Keep:

- The surrounding text intact
- The file's existing tone and format
- Bullet style and indentation consistent with neighbors

## Step 5: Bump `last_updated`

In the target file's YAML frontmatter, update the `last_updated` field to today's date. Check today's date via `date +%Y-%m-%d` if unsure.

## Step 6: Confirm With the User

```
Pinned.
**File**: `Core/Context/Profile.md` (Tools & Stack → Code & AI)
**Added**: "Experimenting with [new tool] for [purpose]"
**last_updated** bumped to YYYY-MM-DD.
```

## Important

- **One insight per `/pin` call.** If the user wants to pin multiple things, prompt them to run it once per insight so each lands in the right place.
- **Don't duplicate.** Before writing, check whether the insight is already captured somewhere else in the file. If it is, update the existing line instead of adding a new one.
- **Respect the file's purpose.** Don't cram weekly stuff into `Profile.md`, and don't put stable facts in `Current State.md`. When in doubt, ask.
- **If `Profile.md` or `Projects.md` exceeds ~500 lines**, flag it to the user so they can decide whether to split or archive. Don't silently let them balloon.
- **If the insight contradicts something already in the file**, flag the contradiction to the user and ask which version is correct before overwriting.
- **`/pin` is the only verb that writes to the canonical context files** (with one exception: `/save` may append a one-line dated entry to `Core/Context/Current State.md`'s "Recent Decisions / Changes" section). Treat the canonical files as `/pin`'s territory.
