init-memory-vault

name

init-memory-vault

description

Scaffold a beginner-friendly Obsidian vault that gives Claude Code persistent, portable memory across conversations. Plain markdown files the user owns — not locked in any provider's database. Trigger when the user asks to "set up memory for Claude Code," "scaffold a portable AI memory vault," "give Claude long-term memory," or types `/init-memory-vault`. For power users who want PARA + Karpathy wiki, use `init-obsidian-vault` instead.

Initialize a Memory Vault for Claude Code

This skill scaffolds an Obsidian vault built around one idea:

Your AI memory, in plain markdown you own. Not locked in a provider's database. Read it, edit it, sync it across devices. If Claude gets retired tomorrow, the files come with you to whatever model is next.

The vault has a flat structure — no PARA, no buckets, no raw/ ingestion. Just a CLAUDE.md, an index.md dashboard, three memory-source files (About me.md, Working preferences.md, Mission.md), a projects/ folder, and free-form notes/. The nightly sync regenerates index.md's top context block so Claude has accurate memory of who the user is every session.

If a user wants PARA, Karpathy wiki, raw-content ingestion, or bucket discipline, point them at the init-obsidian-vault skill instead. This one is deliberately minimal.

Procedure

The user has two paths to seed the vault:

1. Extract from an existing chatbot — fastest if they use ChatGPT/Claude.ai with conversation history or memory.
2. 5-question interview — guided Q&A if they don't.

Either path lands in the same files. ~3 minutes total.

Step 1 — Locate the vault

Ask the user:

Where should I put your memory vault? Paste the absolute path. If you don't have one yet, paste the path where you want me to create it (e.g. ~/Documents/Obsidian/My Memory).

Validate:

• Expand ~ to home.
• If the path exists and contains CLAUDE.md: stop. Tell the user "this directory already has a CLAUDE.md — pick a different path, or back it up first." Do not overwrite.
• If the path doesn't exist, check the parent does. If not, ask whether to create the parents.

Step 2 — Show the scaffold and confirm

<vault>/
├── CLAUDE.md
├── index.md
├── About me.md
├── Working preferences.md
├── Mission.md
├── projects/
├── people/
├── notes/
├── Daily/
└── Attachments/

Confirm. On approval:

1. mkdir -p every directory.
2. Write CLAUDE.md from references/CLAUDE.md.tmpl.
3. Write empty seeds for About me.md, Working preferences.md, Mission.md from their .tmpl files in references/.
4. Write index.md from references/index.md.tmpl. The BEGIN:context-block and BEGIN:toc markers must be in place — the sync script splices into them.

Step 3 — Choose the seeding path

Ask:

Do you currently use ChatGPT or Claude.ai with conversation history / memory enabled? (yes / no)

• Yes → I'll give you a prompt to paste into that chatbot. Its response will seed most of the vault for free; we'll fill any gaps with one or two follow-up questions.
• No → I'll run a 5-question interview (~3 minutes).

Default to interview if the user is unsure.

Step 4a — Extract from existing chatbot

Output the contents of references/extraction-prompt.md as a single fenced code block. Tell the user:

Copy this prompt and paste it into your most-used ChatGPT or Claude.ai conversation (the one with the most context about you). Paste the full response back here when ready.

When the user pastes the response, parse the five sections:

• ## About me → About me.md
• ## Mission → Mission.md
• ## Active projects → one projects/<Name>/README.md per item listed
• ## Working preferences → Working preferences.md
• ## Anything else → appended to About me.md

If a section came back as nothing known, follow up with only the corresponding interview question from references/interview.md. Don't re-ask sections the chatbot already covered.

Common case: the chatbot won't know Working preferences (users rarely articulate them explicitly to chatbots). Plan to follow up on Q4 from the interview after parsing — and use the multi-choice form of Q4 (see interview.md §4), not an open-ended prompt. Most users can't articulate preferences from a blank prompt; they recognize what they want when shown options.

Skip to Step 5.

Step 4b — Run the interview

Ask the questions in references/interview.md one at a time. Wait for each answer before asking the next. Five questions, ~3 minutes. Don't dump them all at once.

Q1, Q2, Q3, Q5 are open-ended text questions. Just ask them as written.

Q4 (Working preferences) is multi-choice. Use AskUserQuestion with the four sub-questions defined in interview.md §4 (tone, code style, workflow, ambiguity handling) in a single tool call. Don't try to type these out as open-ended prompts — the structured form is the whole point. Users can't articulate working preferences from a blank prompt; they pick them out of a list.

If a user answers sparsely on any question, ask one short follow-up. Don't push more.

Step 5 — Populate the files

Map answers to files:

Answer	File	What to write
Q1 (name + role)	About me.md	Short bullets. First bullet is <name> — <role>. Add stage / location / context if it came up.
Q2 (3-year goal)	Mission.md	Quote of the user's stated goal, then 2–3 sentences of why if they gave it.
Q3 (active projects)	projects/<Name>/README.md	One file per project. Short paragraph: what it is, why, where you are. Use the project name verbatim from the user's answer as the folder name.
Q4 (working preferences, multi-choice)	Working preferences.md	One short bullet per non-default selection from the 4 dimensions (tone, code style, workflow, ambiguity). Write the bullet so it reads like a rule, not a label — e.g. selecting "Concise but explanatory" → Concise but explanatory — short answers, but include the *why* for non-obvious choices. For any dimension the user left blank or said "no preference," write a one-liner placeholder like Code style preferences: not articulated yet — will fill in over time. Don't fabricate.
Q5 (anything else)	About me.md	Append as additional bullets.

Then populate index.md's top context block. Same five sections as the source files, but condensed to fit ~250 words total:

• ## About — distilled from About me.md, 1–2 sentences
• ## Mission — distilled from Mission.md, 2–3 sentences inlined (not just a link)
• ## Currently active — one bullet per project: - [[Project Name]] — one-line status
• ## Core principles — (none yet — added when concepts emerge) if no principles came up in interview; otherwise short bullets
• ## Working preferences — distilled from Working preferences.md, 2–5 short bullets

The BEGIN:toc section gets filled by the deterministic TOC builder — but on this initial pass write it inline based on the files you just created:

## Memory sources
- [[About me]] — canonical user memory
- [[Working preferences]] — how the user wants Claude to work
- [[Mission]] — 3-year goal

## Projects
- [[Project Name 1]] — one-line description
- [[Project Name 2]] — ...

Update the Stats block: total entry count, last-updated date.

Step 6 — Deeper context (optional)

The core vault (About / Mission / Active projects / Working preferences) is enough to be useful. But values, heroes, and frameworks are exactly the kind of context that compounds — they let Claude reason in the user's voice, not a generic one. Offer this step, but make every sub-prompt individually skippable.

Use AskUserQuestion to ask the top-level gate first:

{
  "question": "Want to add some optional deeper context? Values you operate by, thinkers/authors who shape your worldview, frameworks you return to. None of it is required — but it noticeably improves the working context.",
  "header": "Deeper context",
  "multiSelect": false,
  "options": [
    { "label": "Yes — let's add some",
      "description": "I'll ask 3 short prompts (values, heroes, frameworks). Each is individually skippable." },
    { "label": "Skip for now",
      "description": "Stop here. You can add Values.md and people/ files anytime — they're picked up automatically by the nightly sync." }
  ]
}

If they pick "Yes," ask each sub-prompt below in order. Each is open-ended; if the user says "skip" or "none," move on without pushing. Don't fabricate.

Sub-prompt A — Values / principles

Are there 2–5 principles you actively operate by? Things like "first-principles thinking," "compound trust over time," "default to the long game," "say no to good things to say yes to great ones." Optional — say "skip" if nothing comes to mind right now.

→ Body of Values.md under ## Principles. One bullet per principle, ~5–15 words each.

Sub-prompt B — Thinkers / heroes / influences

Are there 1–5 thinkers, authors, or public figures whose work shapes how you think? Alive or dead, business or spiritual, technical or philosophical. Give a name + a one-line "why they matter to me" for each, if it comes naturally. Optional.

→ One people/<Name>.md per entry, from references/person.md.tmpl. The "why they matter" line becomes the file body. Use the name verbatim as the file name.

Sub-prompt C — Frameworks / mental models

Any frameworks or mental models you return to a lot? (e.g. inversion, circle of competence, Maslow's hierarchy, PARA, 80/20.) Optional.

→ Append to Values.md under ## Frameworks / mental models. One bullet per framework.

After collecting whatever the user shared:

1. Write Values.md at the vault root from references/Values.md.tmpl, substituting bullets for principles, frameworks, and mantras. Leave any section the user skipped as _(none yet)_. Skip writing the file entirely if the user skipped all three sub-prompts.
2. Write people/<Name>.md files from references/person.md.tmpl. One file per name. Don't write a file for entries where the user gave only a name with no context — file with just the name is OK, but flag to the user that a one-liner would help future-Claude.
3. Update index.md's top context block:
   • ## Core principles — top 2–4 bullets from Values.md's ## Principles section (the rest stays in the file, only the most load-bearing few go in the always-loaded block).
4. Update the TOC's ## People section to list the new files.
5. Update the Stats block counts.

Step 7 — Wire the vault into ~/.claude/CLAUDE.md

Without this step, Claude only sees the vault when running inside it. Wiring it into the user-global config means the vault's index.md is loaded at the start of every Claude Code session, regardless of which project the user is in. This is the difference between "AI memory" and "a folder of markdown files."

Ask the user:

I'd like to add a small section to ~/.claude/CLAUDE.md so Claude reads your vault's index.md at the start of every session and knows where to route cross-project memory. This is the difference between a passive folder of notes and live cross-conversation memory. OK to add? (y/n)

Default: yes (recommended).

Then:

1. Read ~/.claude/CLAUDE.md if it exists.
2. Check whether it already contains <!-- BEGIN:memory-vault-wiring -->:
   • Already wired → check if the existing block points at the same vault path. If yes, skip with a one-line "already wired." If different vault, ask: "your global config already points at <existing_path> — replace with <new_path> or keep both? (replace / keep-existing / both)". For "both," the user manages this manually — print a warning and stop.
   • Not yet wired → append the rendered snippet from references/global-claude-md-snippet.md.tmpl (substitute {{VAULT_PATH}} with the absolute vault path). If the file doesn't exist yet, create it with just the snippet as the entire content.
3. Tell the user what changed in a single sentence: "Added a ## Memory vault section to ~/.claude/CLAUDE.md pointing at <vault>. Open a fresh Claude session in any project to confirm — ask 'what do you know about me?' and it should answer without grepping."

Step 8 — Install the nightly sync

Follow references/sync-cron.md. The user agrees to install it, or skips. Either way, tell them they can install later with the same command.

Default plist label is com.user.memory-vault-sync (different from init-obsidian-vault's com.user.claude-vault-sync, so both can coexist if the user has both vaults).

Step 9 — Final summary

Tell the user:

Memory vault initialized at <path>.

{{If wiring step ran:}} ~/.claude/CLAUDE.md now points at this vault — Claude reads index.md at the start of every session, in every project.

{{If wiring step was skipped:}} Note: you skipped the wiring step, so Claude only reads this vault when working inside it. Run the skill again or manually add a ## Memory vault section to ~/.claude/CLAUDE.md if you want global access.

1. Open Obsidian and add this vault as a new vault (Open another vault → Open folder as vault).
2. {{If wiring step ran:}} Open a fresh Claude Code conversation in any project. Ask it "what do you know about me?" — it should answer from the vault's index.md without grepping.
3. As you work, add to About me.md and Working preferences.md over time. The nightly sync folds new bullets into index.md's top block within 24 hours.
4. Use notes/ as a free-form sandbox — anything goes, no rules.
5. The status log feature: every Claude session in a project creates a dated projects/<project>/<date>_status.md with "What you worked on" and "Recommended next steps." Open Obsidian in the morning, see what to do next.
6. Optional: git init && git add . && git commit -m "init" from the vault root for version history. Or use Obsidian Sync / iCloud / Dropbox — your memory follows you.

Failure modes

• Path has spaces: quote all paths in mkdir, cp, etc.
• User wants to abort mid-interview: save partial state (write whatever's been answered so far), tell them to re-run later. Don't push.
• User answered all five questions with one-liners: that's fine — the vault is meant to grow. Don't pad with fabricated content.
• CLAUDE.md already exists at the path: abort. Tell user to pick a different path or back up first. Never overwrite.
• User asks why this isn't init-obsidian-vault: the other skill scaffolds PARA + Karpathy wiki + content-ingestion workflow. This one scaffolds just the memory layer. If they want both, they can run the other skill in a different directory.
• User declines the global config wiring (Step 7): that's fine — scaffolding still works, the vault is just isolated to itself. Tell them what they lose: cross-conversation memory only fires when working inside the vault directory. Re-running the skill re-offers the wiring.
• User skips Step 6 (deeper context): that's the default. The vault works fine without Values.md or people/. Tell them they can add either anytime — just tag Values.md with memory-source so the nightly sync picks it up, and place people/<Name>.md files in people/ for them to auto-appear in the TOC.
• ~/.claude/CLAUDE.md already points at a different vault (existing <!-- BEGIN:memory-vault-wiring --> block with a different path): ask the user explicitly. Don't silently overwrite — they may be intentionally using two vaults (e.g. work vs. personal). Default to "keep existing" if they're unsure.