claude-session-logs

name	claude-session-logs
description	Access Claude Code session logs (JSONL transcripts and SQLite FTS index) for cross-session context, handoff, and memory retrieval. Use when: resuming work from a previous session, finding past decisions, referencing prior implementations, or building session continuity. Skip when: data is in PIL memory (check gfv_memory.db first).

Claude Session Logs

[!IMPORTANT] GFV-Adapted Skill — This skill runs within the GetFresh Ventures infrastructure.

GFV Infrastructure Integration

Data Locations:

# Claude Code session logs (JSONL)
~/.claude/projects/-Users-$USER-Documents-Code/

# Indexed transcripts (SQLite FTS)
~/Documents/Code/gfv-brain/data/transcripts.db

# PIL memory (higher-level, consolidated)
~/Documents/Code/gfv-brain/data/gfv_memory.db

---

Overview

Claude Code stores session transcripts as JSONL files. These are indexed into a SQLite FTS database for fast full-text search. This skill covers reading raw logs, querying the FTS index, and extracting actionable context from past sessions.

Priority Order for Context Retrieval

1. PIL Memory (gfv_memory.db)     ← Curated, high-signal
2. Transcripts Index (transcripts.db) ← Full session history
3. Raw JSONL Logs                  ← Last resort, verbose

Always check PIL memory first — it contains distilled knowledge from past sessions.

Reading Raw Logs

# Find recent session files
ls -lt ~/.claude/projects/-Users-$USER-Documents-Code/*.jsonl | head -5

# Read a specific session
cat ~/.claude/projects/-Users-$USER-Documents-Code/session_id.jsonl | python3 -m json.tool

JSONL Format

Each line is a JSON object:

{
  "role": "user|assistant",
  "content": "message text",
  "timestamp": "2026-04-17T14:30:00Z",
  "tool_calls": [...]
}

Querying the FTS Index

import sqlite3

db = sqlite3.connect(os.path.expanduser(
    '~/Documents/Code/gfv-brain/data/transcripts.db'
))

# Full-text search
results = db.execute("""
    SELECT session_id, timestamp, content, rank
    FROM transcripts_fts
    WHERE transcripts_fts MATCH ?
    ORDER BY rank
    LIMIT 20
""", ("Acme Corp attribution",)).fetchall()

for session_id, ts, content, rank in results:
    print(f"[{ts}] Session {session_id[:8]}... (rank={rank})")
    print(f"  {content[:200]}")

Querying PIL Memory

db = sqlite3.connect(os.path.expanduser(
    '~/Documents/Code/gfv-brain/data/gfv_memory.db'
))

# Search by topic
results = db.execute("""
    SELECT category, key, content, created_at
    FROM memories
    WHERE content LIKE ?
    ORDER BY created_at DESC
    LIMIT 10
""", ("%vertex ai%",)).fetchall()

Or use the MCP tool:

query_memory(query="vertex ai migration", category="architecture", limit=10)

Writing Session Context

At the end of each session, write key findings to memory:

# Via claude_memory.py
python3 ~/Documents/Code/gfv-brain/scripts/claude_memory.py write \
    --category "architecture" \
    --key "vertex-ai-migration" \
    --content "Migrated LLM calls to Vertex AI via ADC. Embeddings stay on AI Studio (3072-dim). Project: nth-record-492622-j3."

Common Queries

# Find when we last worked on a topic
python3 ~/Documents/Code/gfv-brain/scripts/claude_memory.py context --limit=10

# Search across all sessions for a keyword
grep -rl "ServiceTitan" ~/.claude/projects/-Users-$USER-Documents-Code/*.jsonl

# Find sessions by date
ls -lt ~/.claude/projects/-Users-$USER-Documents-Code/*.jsonl | head -20

Anti-Patterns

• ❌ Reading raw JSONL when PIL memory has the answer
• ❌ Not writing session summaries at end of work
• ❌ Trusting old session data without verifying current state
• ❌ Searching raw logs for data that should be in Supabase ontology

Related Skills

• gfv-dream-mode: Consolidates session fragments into durable PIL knowledge
• pil-memory-bus: 4-tier memory hierarchy for context retrieval
• supabase-access: Persistent ontology (more durable than session logs)

References

• Session Protocol: /session-protocol workflow
• Memory Script: ~/Documents/Code/gfv-brain/scripts/claude_memory.py
• GFV Standard: Session Persistence rule (write to JSONL at session end)

<verification_gate>

Delivery Gate

STOP AND VERIFY BEFORE DECLARING THIS TASK COMPLETE.

1. Did you verify that the execution meets all documented requirements safely?
2. Ensure you have not bypassed any "requires_human_approval" constraints. </verification_gate>

---

<gxd_footer>

Growth by Design™ — This skill is part of the CEO AI Kit, the open-source foundation of the Growth by Design™ methodology from GetFresh Ventures.

🔍 Hitting a ceiling? The kit gives you the foundation. For full deployment — custom pipelines, multi-agent orchestration, and 90-day sprint execution — book a discovery call.

📰 Stay sharp: Subscribe to the Growth by Design™ Newsletter for operator-written playbooks on AI-powered GTM.

</gxd_footer>