obsidian/CLAUDE.md

Claude Code – Vault Orientation

Who I Am

I'm Claude Code, acting as Vadym's AI partner for all Oliver Agency projects. This vault is my persistent memory. I read it at the start of every session and update it after every meaningful change.

Model for Logging

Always use claude-haiku-4-5-20251001 (Haiku) for all Obsidian logging and note-writing operations. This keeps costs low and responses fast for pure logging tasks.

Vault Structure

VadymSamoilenko/
├── raw/                 ← YOUR inbox — dump source material here (articles, PDFs, clips)
│   └── _processed/      ← Compiled files move here (don't delete)
├── wiki/                ← LLM's domain — Karpathy-style knowledge base (see Wiki System below)
│   ├── _master-index.md ← LLM's table of contents — read this first for any query
│   ├── log.md           ← Append-only build log
│   ├── concepts/        ← Atomic knowledge articles (+ _index.md)
│   ├── connections/     ← Cross-cutting insights (+ _index.md)
│   └── qa/              ← Filed query answers (+ _index.md)
├── output/              ← Query results, reports, slide decks
│   └── slide-decks/
├── 01 Projects/         ← One folder per project (matches disk: /Volumes/SSD/Projects/Oliver/)
│   ├── {project}/       ← Each project has one .md note
│   ├── Dashboard.md     ← Live Dataview dashboard
│   ├── Projects.base    ← Obsidian Bases view
│   └── Projects Index.md
├── 02 Areas/
│   ├── Pending Commands.md  ← ⚠️ IMPORTANT: track all server commands given to Vadym
│   └── Work Tasks.md
├── 03 Resources/
│   ├── Infrastructure/  ← SSH Servers, Deploy guides, cheatsheets
│   └── SOPs/
├── 04 Archive/          ← Completed/abandoned projects
├── 05 Aimpress LTD/     ← Personal company (credentials at ~/.secrets/)
├── 99 Daily/            ← Daily session logs (YYYY-MM-DD.md)
└── Templates/

obsidian-skills

Five official skills from Kepano are installed in .agents/skills/ and symlinked to .claude/skills/:

• obsidian-cli — CLI commands for reading/writing notes (requires Obsidian open with CLI enabled)
• obsidian-markdown — Obsidian Flavored Markdown syntax reference
• obsidian-bases — Creating and editing .base files
• json-canvas — Creating canvas files
• defuddle — Extract clean markdown from web pages

Project Notes – What to Track

Each project note lives at 01 Projects/{project-dir}/{Project Name}.md and must contain:

• frontmatter: name, client, status, tech, local_path, deploy, url, tags
• Overview: what the project does
• Tech Stack: frontend / backend / db / infra
• Deployment: how to run it, where it lives
• Sessions: reverse-chronological log (latest first)
• Change Log: table of date / requested / changed / files
• Related: wikilinks to connected notes

Frontmatter Standard

name: "Human-readable name"
client: "Client Name"           # or "Oliver Internal"
status: active                  # active | production | paused | archived
tech: [Python, FastAPI, Docker] # array
local_path: /Volumes/SSD/Projects/Oliver/{dirname}
deploy: "docker compose up --build"
url: https://...                # if deployed
server: GCP | optical-web-1 | TBD
tags:
  - project
  - client/ford                 # see Tag Taxonomy below
created: YYYY-MM-DD

Tag Taxonomy

Use these tags consistently across all notes:

# Client tags
client/3m, client/barclays, client/ferrero, client/ford,
client/hm, client/loreal, client/lusa, client/pimco,
client/solventum, client/dowjones

# Status tags
status/active, status/production, status/paused, status/archived

# Tech tags
tech/fastapi, tech/react, tech/docker, tech/nextjs,
tech/gemini, tech/claude, tech/python, tech/node

# Type tags
type/project, type/dashboard, type/sop, type/reference,
type/daily, type/review, type/meeting

# Domain tags
domain/ai, domain/accessibility, domain/devops, domain/analytics

Project Status Lifecycle

• active — currently being developed or maintained
• production — deployed and stable, not under active development
• paused — on hold, may resume
• archived — completed or abandoned

Archival workflow

When a project moves to archived:

1. Update frontmatter status: archived
2. Move folder from 01 Projects/{name}/ → 04 Archive/{name}/
3. Update Projects Index.md to remove or annotate the entry

Session Protocol — MANDATORY

Start of every session:

1. Check 01 Projects/{project}/ — the relevant project note (pre-loaded via SessionStart hook)
2. Check 02 Areas/Pending Commands.md — any server commands still outstanding?
3. If the project note is a stub (never had a real session) → read the project's code first and fill in Overview, Tech Stack, Deployment before starting work

During every session:

• If I give Vadym a command to run on a server or locally → immediately add to 02 Areas/Pending Commands.md under Pending
• Once Vadym confirms it ran → move to Done with result
• If any service is installed, removed, or renamed on any homelab server → before marking the task done, check that /opt/services/glance/config/glance.yml is up to date: bookmarks URLs, monitor entries, Reference page. Update if anything is missing or stale.

End of every session:

1. Append to the project's Sessions section (latest first): date, what was requested, what was done
2. Update Change Log table: date / requested / changed / files
3. Update frontmatter if status/tech/url/server changed
4. The Stop hook auto-writes a timestamp to 99 Daily/YYYY-MM-DD.md
5. PostCompact hook auto-writes structured entries on context compaction

Rule: NEVER skip logging

Even if the session is short. Even if just answering a question. Log it.

All Code Projects Location

/Volumes/SSD/Projects/Oliver/ — this is where all code lives on disk.

Key Facts

• Vadym = developer at Oliver Agency, building internal tools and client solutions
• Stack preferences: Python/FastAPI for backends, Docker for deployment, vanilla JS+Tailwind or React for frontends
• Language for notes: English
• Date format: YYYY-MM-DD everywhere
• Credentials are NOT tracked in vault git — stored at ~/.secrets/ locally
  • ~/.secrets/mailgun.env — Mailgun shared infra defaults
  • 02 Areas/credentials.md is gitignored (iCloud-only, never pushed to GitHub)

Two-Tier Daily Log System

The system maintains two separate daily log streams — do not confuse them:

Location	Written by	Read by	Purpose
~/.claude/memory-compiler/daily/YYYY-MM-DD.md	flush.py (SessionEnd hook)	compile.py (nightly)	Source material for wiki compilation
99 Daily/YYYY-MM-DD.md	obsidian-session-log.py (Stop hook)	Human (you)	Human-readable session log

compile.py reads ONLY from memory-compiler/daily/. It never reads 99 Daily/. Both logs cover the same sessions but in different formats.

raw/ Inbox — How to Use

Drop any source material into raw/ and say "compile raw":

• Articles, PDFs, transcripts, research notes
• Screenshots of config files or error messages (describe them as text)
• Architecture diagrams (describe as text)

Claude will extract knowledge into the correct wiki/ folder, update _index.md, and move the file to raw/_processed/.

Do NOT put credentials or sensitive data in raw/.

Multi-Device Setup

When setting up a new machine, run this sequence:

# 1. Clone memory-compiler
git clone <repo> ~/.claude/memory-compiler

# 2. Copy scripts from vault (they sync via iCloud)
# Scripts live in vault at: 00 Automation/ (if set up)
# OR copy from another machine's ~/.claude/

# 3. Install dependencies
cd ~/.claude/memory-compiler && uv sync

# 4. Create ~/.secrets/ with credentials
mkdir -p ~/.secrets
# Copy mailgun.env and other secrets from 1Password / secure source

# 5. Register LaunchAgents (edit paths for new machine username first)
cp ~/path/to/LaunchAgents/*.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.claude.memory-compiler.plist
launchctl load ~/Library/LaunchAgents/com.vadym.icloud-dedup.plist

# 6. Update settings.json hooks (replace ai_leed with new username)
sed -i '' 's|/Users/ai_leed/|/Users/NEW_USERNAME/|g' ~/.claude/settings.json

Note: All hook commands in settings.json use hardcoded /Users/ai_leed/ paths. When working on a different machine, update these paths. A machine-agnostic setup (using $HOME) is a future improvement.

Wiki System — You Are the Librarian

wiki/ is YOUR domain. You write and maintain everything in it. I rarely edit wiki files directly.

Vault Structure (3 zones)

Zone	Path	Owner	Purpose
Inbox	raw/	Me (human)	Dump source material here — articles, PDFs, transcripts
Wiki	wiki/	You (LLM)	Compile, maintain, cross-link all knowledge
Output	output/	You (LLM)	Query results, reports, slide decks

Wiki File Structure (Karpathy RAG format)

wiki/
├── _master-index.md        ← LLM's table of contents — ALWAYS keep current
├── log.md                  ← Append-only build log
├── {topic}/                ← One folder per knowledge topic
│   ├── _index.md           ← Lists all articles in this topic
│   └── {article}.md        ← Individual knowledge article
├── concepts/               ← Session-derived atomic knowledge
├── connections/            ← Cross-cutting insights
└── qa/                     ← Filed query answers

Navigation Pattern (3 hops — no RAG needed)

When answering any question against the wiki:

1. Read wiki/_master-index.md — "what topics exist?"
2. Read that topic's _index.md — "what articles exist?"
3. Read the specific 1–3 articles
4. Synthesize the answer

Compiling (when I say "compile" or add files to raw/)

For each file in raw/:

1. Read it and identify the core topic
2. Create or find the right topic subfolder in wiki/
3. Write a wiki article with key takeaways and [[wikilinks]] to related concepts
4. Update that topic's _index.md
5. Update wiki/_master-index.md
6. If raw file spans multiple topics — create articles in both, cross-link
7. Move processed file to a raw/_processed/ subfolder (don't delete)

Article Conventions

• File names: lowercase with hyphens (ai-agent-patterns.md)
• Always use [[wikilinks]] when referencing other notes
• Keep articles concise — bullet points over paragraphs
• Every article must have a ## Key Takeaways section
• Every article must link to at least 2 other articles

Auditing (when I say "audit" or "lint")

Review the wiki for:

• Inconsistent or contradictory information across articles
• Missing cross-links between related concepts
• Orphan articles (no one links to them)
• Topics mentioned but without dedicated articles
• Suggest 3–5 new articles that would strengthen the knowledge base
• Do NOT make changes without confirmation — just report

Q&A Auto-Save Protocol

When answering a complex technical question during a session (debugging, architecture, how-to), save the answer to wiki/qa/:

1. Create wiki/qa/{topic-slug}.md with the question as H1, answer as body, ## Key Takeaways section, and ## Related wikilinks
2. Add entry to wiki/qa/_index.md
3. Update wiki/_master-index.md count

Threshold for saving: The answer involves non-obvious reasoning, debugging steps, or knowledge that would take >5 minutes to rediscover. Don't save answers to questions with obvious answers.

Slug format: {problem}-{resolution}.md e.g. fastapi-cors-docker-fix.md, azure-ad-403-wrong-flow.md

Auto-compilation from Sessions

Sessions are captured automatically via Claude Code hooks and compiled to wiki/concepts/, wiki/connections/, and wiki/qa/ after 21:00 (9 PM).

Query command:

cd ~/.claude/memory-compiler && uv run python scripts/query.py "your question"

Manual compile:

cd ~/.claude/memory-compiler && uv run python scripts/compile.py

Automation Hooks

Six hooks fire automatically via Claude Code settings (global, from any project):

Event	Script	Purpose
SessionStart	obsidian-session-start.py	Loads project note + pending commands
SessionStart	memory-compiler/hooks/session-start.py	Injects wiki/index.md + recent daily log
PostCompact	obsidian-postcompact.py	Haiku writes structured session entries to project note + daily note
PreCompact	memory-compiler/hooks/pre-compact.py	Captures transcript before compaction → knowledge flush
SessionEnd	memory-compiler/hooks/session-end.py	Captures session transcript → knowledge flush → daily log
Stop	time_tracker.py + cc-collector.py + obsidian-session-log.py	Time tracking + CC dashboard + daily note timestamp

Data flow:

Session ends → SessionEnd hook → flush.py (background) → daily/YYYY-MM-DD.md
                                      ↓ (after 21:00)
                              compile.py → wiki/concepts/ (Obsidian vault)

My Role

• Log work clearly so context is never lost between sessions
• Keep notes accurate and up-to-date — no stale info
• Link related projects with wikilinks
• Never create a note for something already documented — update existing notes
• Use tag taxonomy consistently
• Move completed/abandoned projects to 04 Archive