Vault Import

Vault Import — Backfill Historical Sessions

Discover historical Claude Code sessions, summarize them via parallel sub-agents, and write structured session notes to the Obsidian vault. Skips sessions already present in the vault.

Tools needed: Bash, Write, Read, Skill (for /context-shield sub-agents)

Prerequisites:

• /conversation-search skill must be installed
• /context-shield skill must be installed
• Obsidian Brain must be configured (run /obsidian-setup if not)

Procedure

Follow these steps exactly. Do not skip steps or reorder them.

Step 1 — Read config

Run:

cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
python3 -c '
import sys, os
import glob; sys.path.insert(0, max(glob.glob(os.path.expanduser("~/.claude/plugins/cache/*/obsidian-brain/*/hooks")), default="hooks"))
from obsidian_utils import load_config
c = load_config()
if not c.get("vault_path"):
    print("ERROR: vault_path not configured", file=sys.stderr)
    sys.exit(1)
print("VAULT=" + c["vault_path"])
print("SESS=" + c.get("sessions_folder", "claude-sessions"))
print("INS=" + c.get("insights_folder", "claude-insights"))
'

Parse each output line as KEY=VALUE, splitting on the first =.

If the command exits non-zero or prints ERROR, tell the user:

> Config not found. Please run /obsidian-setup first to configure your Obsidian vault.

Stop here if config is missing.

Store the extracted values as VAULT_PATH and SESSIONS_FOLDER (default claude-sessions).

Step 2 — Validate vault access

Run:

test -d "$VAULT_PATH/$SESSIONS_FOLDER" && test -w "$VAULT_PATH/$SESSIONS_FOLDER" && echo "OK" || echo "FAIL"

If FAIL, tell the user:

> The sessions folder $VAULT_PATH/$SESSIONS_FOLDER does not exist or is not writable. Run /obsidian-setup to fix this.

Stop here if FAIL.

Step 3 — Parse arguments

Parse the user's invocation to extract:

• Time range: A duration like 7d, 14d, 30d. Default is 7d if not specified.
• Project filter: An optional project: argument (e.g. project:api-service).

Examples:

• /vault-import — last 7 days, all projects
• /vault-import 30d — last 30 days, all projects
• /vault-import project:api-service 14d — last 14 days, only api-service
• /vault-import project:api-service — last 7 days, only api-service

Store as TIME_RANGE and PROJECT_FILTER (empty string if no filter).

Step 4 — Discover sessions

Use the /conversation-search skill's underlying search script to find sessions matching the time range and project filter.

Run:

bash ~/.claude/skills/conversation-search/scripts/search-conversations.sh --days  --format jsonl

If a project filter is specified, add --project to the command.

If the script is not found, fall back to manually scanning ~/.claude/projects/ for session JSONL files modified within the time range:

find ~/.claude/projects/ -name "*.jsonl" -mtime - -type f 2>/dev/null

Parse the output to build a list of sessions. Each session needs:

• session_id — extracted from the filename or JSONL content
• session_path — absolute path to the JSONL file
• project — extracted from the directory path or JSONL content
• date — file modification date

If no sessions are found, tell the user:

> No sessions found in the last `` matching your filters.

Stop here if no sessions found.

Step 5 — Filter already-imported sessions

Check the vault for existing session notes that match discovered session IDs.

Run:

grep -rl "session_id:" "$VAULT_PATH/$SESSIONS_FOLDER/" 2>/dev/null | xargs grep -l "" 2>/dev/null

More efficiently, build a single grep command:

for f in "$VAULT_PATH/$SESSIONS_FOLDER/"*.md; do
  head -20 "$f" 2>/dev/null
done | grep "session_id:" | awk '{print $2}'

Collect all session IDs already in the vault into a set called EXISTING_IDS. Remove any session from the discovered list whose session_id is in EXISTING_IDS.

Store the remaining sessions as PENDING_SESSIONS and the count of skipped sessions as SKIPPED_COUNT.

If no pending sessions remain, tell the user:

> All ` sessions from the last ` are already in the vault. Nothing to import.

Stop here if nothing to import.

Otherwise, report:

> Found ` sessions, already imported, ` to import.

Step 6 — Summarize sessions with parallel sub-agents

This is the performance-critical step. Use parallel sub-agents to maximize throughput.

For each session in PENDING_SESSIONS, delegate to a /context-shield sub-agent with this prompt:

> Read the Claude Code session transcript at ``. Extract and return a structured summary with these exact sections: > > - Summary: 2-3 sentence overview of what was accomplished > - Key Decisions: Bulleted list of architectural or design choices made > - Changes Made: Bulleted list of files created, modified, or deleted > - Errors Encountered: Bulleted list of errors hit and how they were resolved (or "None") > - Next Steps: Bulleted list of follow-up tasks mentioned (or "None") > - Git Info: Branch name, commit hashes if any (or "None") > > Keep the total output under 300 tokens. Return only the structured summary, no preamble.

Parallelism rules:

• Launch up to 5 sub-agents in parallel (sessions are independent — no shared state)
• Wait for the batch to complete before launching the next batch
• If a sub-agent fails or times out, log the error and skip that session — do not block the entire import

Collect the distilled summaries. Store each as SUMMARY keyed by session_id.

Step 7 — Construct and write session notes

For each successfully summarized session, construct a vault note with this format:

---
type: claude-session
date: 
session_id: 
project: 
git_branch: 
duration_minutes: 
imported: true
imported_date: 
tags:
  - claude/session
  - claude/project/
  - claude/imported
---

# 

## Key Decisions

## Changes Made

## Errors Encountered

## Next Steps

## Git Info

Generate the filename using the same convention as other session notes:

1. Date: YYYY-MM-DD (session date)
2. Slug: Title lowercased, spaces to hyphens, non-alphanumeric (except hyphens) removed, truncated to 50 chars
3. Hash: 4-character hex hash from the session_id: echo -n "" | md5 | cut -c1-4 (macOS) or echo -n "" | md5sum | cut -c1-4 (Linux). Do NOT use tail -c 4 — it counts the trailing newline as a byte and returns only 3 visible characters.

Final filename: YYYY-MM-DD--.md

Write each note:

mkdir -p "$VAULT_PATH/$SESSIONS_FOLDER"

Use the Write tool to write the file, then:

chmod 644 "$VAULT_PATH/$SESSIONS_FOLDER/"

Step 8 — Report results

Print a summary report:

> Vault import complete! > > - Imported: ` sessions > - **Skipped (already in vault):** sessions > - **Failed:** sessions (if any) > - **Time range:** last > - **Project filter:** (or "all projects") > > New notes written to: $VAULTPATH/$SESSIONSFOLDER/`

If any sessions failed, list them:

> Failed sessions: > - `: `

Offer follow-up:

> Run /vault-import to go further back, or open Obsidian to browse the imported sessions.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abhattacherjee
• Source: abhattacherjee/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.