Samaritan

An AI PM operating system for capture, file, recall, and weekly synthesis. Brokers between Obsidian (prose), Notion (structured rows), a task manager (TickTick / Todoist / Linear), and Cowork's persistent memory.

Built for solo builders and PMs who want their notes, decisions, and tasks to flow into one queryable system without manual filing. Capture is friction-free; structured deltas land in Notion as the queryable backbone; synthesis runs on a schedule.

Read the story

Three posts walking through what this is, how it works, and the design calls behind it:

• 📖 Samaritan — overview & day in the life — what the system does and what living inside it feels like.
• ⚙️ AI PM OS — skills, triggers, jobs — the operational layer: the 8 capture skills, the two-of-three trigger model, the scheduled synthesis cadence.
• 🧠 Second brain — vector DB skipped — why this is a structured-broker design and not a vector-RAG one, and the trigger to revisit.

What you get

8 capture skills installable as a single Claude Code plugin:

Skill	What it does
/log	Hourly journal capture (1–3 sentences, project-tagged). Telegram-aware.
/capture	Dump a raw thought to today's Inbox. No routing, no questions — fast.
/decision	File a structured Decision row to Notion + linked Obsidian update + task-manager next steps.
/meeting	Process a meeting into a structured Obsidian note + extracted Notion rows + tasks. Fireflies-aware.
/file	Direct typed Notion file (decision / insight / person / project). No conversational extraction.
/wrap	Session-close: silently file decisions, insights, tasks from the conversation. The single highest-leverage skill.
/recall	Grounded query across Notion + Obsidian + task manager. Every claim cited.
/weekly	7-day digest written to Obsidian. Time allocation, decisions, stuck items, next-week focus.

Plus:

• AGENT_OS.md — the operating contract Claude reads on session start (routing rules, skill behavior, scheduled jobs, Notion schemas).
• CLAUDE.md — orientation pointer.
• Home.md — Obsidian dashboard with Dataview queries (today's note, active projects, weekly density, recent meetings).
• Templates/ — 4 Obsidian templates (Daily / Weekly / Meeting / Project).
• dashboard/dashboard.html — Cowork artifact source for a cross-store live dashboard (today's tasks, this week, active projects, recent decisions, etc.).

Prerequisites

• Cowork (Anthropic's desktop app for knowledge work)
• Claude API access (Pro / Max / Team / Enterprise)
• Obsidian with the Dataview community plugin (required for Home.md)
• Notion workspace (you'll create 4 databases)
• A task manager with an MCP connector (TickTick, Todoist, Linear, etc.)

Optional but recommended:

• Journals Obsidian community plugin for multi-stream daily/weekly notes
• Telegram bot via Claude Code Channels for mobile capture

Quick start

For the impatient. Detailed setup in the next section.

# 1. Clone this repo into your Obsidian vault (or a sub-folder of it)
git clone https://github.com/{{YOUR_GH}}/samaritan.git ~/Documents/Obsidian/Samaritan

# 2. Install Dataview in Obsidian → Community plugins → Browse → Dataview

# 3. Create 4 Notion databases (schemas in AGENT_OS.md) and note their data source IDs

# 4. Replace placeholders in AGENT_OS.md and samaritan-plugin/skills/*/SKILL.md:
#    {{YOUR_VAULT_ROOT}}, {{YOUR_PROJECTS_DS_ID}}, {{YOUR_DECISIONS_DS_ID}},
#    {{YOUR_PEOPLE_DS_ID}}, {{YOUR_INSIGHTS_DS_ID}},
#    {{YOUR_TASK_MANAGER_MCP_ID}}, {{YOUR_NOTION_MCP_ID}}

# 5. Install the plugin
cd samaritan-plugin
zip -r ../samaritan.plugin .
# Then drag samaritan.plugin into Cowork's plugin install UI

# 6. Test
# In Cowork: type "/log testing samaritan"
# Should append to today's daily note. Type "/wrap" to verify silent filing.

Detailed setup

1. Create your Obsidian vault folder

This can be a brand-new vault or a sub-folder inside an existing one. The skills assume the vault is at {{YOUR_VAULT_ROOT}}/Samaritan/ — adjust if you put it elsewhere.

2. Drop these files into the vault root

• AGENT_OS.md — the operating contract
• CLAUDE.md — the orientation pointer
• Home.md — the dashboard
• Templates/ — all 4 template files

3. Install Dataview

Settings → Community plugins → Browse → search "Dataview" → install + enable. Required for Home.md to render the tables.

4. (Optional) Install Journals

Settings → Community plugins → Browse → search "Journals" → install. Configure two streams:

• Samaritan Daily — folder Samaritan/Areas/Daily/, format YYYY-MM-DD, template Samaritan/Templates/Daily Note
• Samaritan Weekly — folder Samaritan/Areas/Weekly/, format YYYY-[W]ww, week-start Monday, template Samaritan/Templates/Weekly Note

This gives you Cmd-P → Journals: Open today's note for instant daily navigation. Without it, the /log skill still creates daily notes on demand.

5. Create the 4 Notion databases

Schemas in AGENT_OS.md. Easiest path: create them by hand in Notion, then capture each database's data source ID (the UUID in the URL, looks like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

The four databases:

DB	Key fields	Relations
Projects	Name, Status, Owner, Area, Obsidian Link, Task-Manager Project ID, Last Updated	Hub
Decisions	Decision, Rationale, Project (relation), Decided By (relation), Decided On, Reversibility, Source, Status, Evidence	→ Project, → People
People	Name, Role/Org, Relationship Context, Last Interaction	↔ Projects
Insights	Insight, Detail, Source, Tags, Captured On	↔ Projects

6. Replace placeholders

Throughout AGENT_OS.md, samaritan-plugin/skills/*/SKILL.md, and dashboard/dashboard.html:

• {{YOUR_VAULT_ROOT}} → your absolute vault path
• {{YOUR_PROJECTS_DS_ID}}, {{YOUR_DECISIONS_DS_ID}}, {{YOUR_PEOPLE_DS_ID}}, {{YOUR_INSIGHTS_DS_ID}} → your Notion data source IDs
• {{YOUR_TASK_MANAGER_MCP_ID}} → your task manager MCP namespace (the unique ID Cowork assigns)
• {{YOUR_NOTION_MCP_ID}} → your Notion MCP namespace

Use search-and-replace — sed -i or your editor's project-wide replace will work.

7. Install the plugin

Two paths:

Easier: zip the samaritan-plugin/ directory as samaritan.plugin and drag it into Cowork's plugin install UI:

cd samaritan-plugin
zip -r ../samaritan.plugin .

Manual: copy the directory into Cowork's plugin install location (managed by Cowork, not ~/.claude/).

After install, you should see samaritan:log, samaritan:wrap, etc. in your available skills list.

8. Test

In Cowork:

/log testing samaritan

Should append to today's daily note at {{YOUR_VAULT_ROOT}}/Samaritan/Areas/Daily/YYYY-MM-DD.md. Then:

/wrap

Should report what got filed (probably just the log entry plus the session line).

9. (Optional) Set up the dashboard

dashboard/dashboard.html is the Cowork artifact source. To publish:

1. Open Cowork.
2. Use the create_artifact MCP tool with the HTML file path.
3. The artifact appears in your sidebar and refreshes from Notion + task manager on every reload.

10. (Optional) Telegram routing for mobile capture

Set up a Telegram bot per Claude Code Channels docs. Once configured, /log from your phone routes into the desktop Claude Code session and appends to today's daily note.

File reference

File	Purpose
AGENT_OS.md	Operating contract — routing rules, skill behavior, scheduled jobs, Notion schemas. Claude reads on session start. Keep under 3 pages.
CLAUDE.md	Orientation pointer — ~40 lines. Tells Claude to read AGENT_OS.md and lists the four stores.
Home.md	Dashboard at vault root. Dataview queries showing today's note, active projects, weekly density, recent meetings.
Templates/Daily Note.md	Daily journal template (Morning briefing / Hourly Log / Inbox / Session sections).
Templates/Weekly Note.md	Weekly digest template (TL;DR, Time allocation, Decisions, Insights, Stuck, Next week).
Templates/Meeting Note.md	Meeting note template (Context / Discussion / Decisions / Next Steps / Open Questions).
Templates/Project.md	Project file template with frontmatter (status, area, owner, notion_id).
samaritan-plugin/.claude-plugin/plugin.json	Plugin manifest.
samaritan-plugin/skills/<name>/SKILL.md	One per capture skill. Self-contained markdown with YAML frontmatter + behavior contract.
dashboard/dashboard.html	Cowork artifact source (~400 lines). Uses Chart.js. Calls 3 MCP tools.
HANDOFF.md	Detailed reference for Claude Code helping a fork get this running — every skill, every file, debugging tips.

Gotchas to know upfront

A few non-obvious things that bit during the original build:

• Plugin validation is strict about YAML. Don't use <text> placeholders in skill descriptions (rejected). Don't put unquoted colons inside quoted phrases like "final call: ship X" (YAML mapping error). Use [text] and rephrase to avoid colons.

• Plugins don't install to ~/.claude/. Cowork manages plugin install in its own app-support directory. ~/.claude/skills/ is for standalone skills only.

• Dataview path scoping. If you put Samaritan as a sub-folder of a larger Obsidian vault, every Dataview FROM clause needs the parent prefix (FROM "Samaritan/Areas/Daily", not FROM "Areas/Daily"). The queries in Home.md already use the prefix; remove it if Samaritan is your vault root.

• Counting ### HH:00 headings. Use file.headings not file.lists. The daily template has no other H3 headings, so length(filter(file.headings, (h) => h.level = 3)) is the cleanest counter.

• Cowork's window.cowork.callMcpTool returns MCP Content protocol responses. Not raw MCP envelopes. The dashboard's unwrapList() function handles both per-record responses (task manager) and envelope responses (Notion). Don't simplify this away — without it the cards appear empty despite successful API calls.

• Notion semantic search can't filter by Status or Tags property values. For "blocked Projects" or "Insights tagged open-question," pull all rows with a broad query ("project", "insight") and filter client-side by title patterns.

HANDOFF.md has the full reference.

Customization

• The 4 Notion databases have fixed schemas. Field names can be renamed if you also update the corresponding skill files.
• The capture skills are self-contained markdown files; edit to change behavior.
• The dashboard is intentionally simple; fork and add cards.
• The trigger model (live capture / source sweep / session close) is load-bearing — don't remove the source sweep; it's what catches what you forget.

Philosophy

• Capture is dumb on purpose. The /capture skill doesn't classify or route at capture time. The nightly inbox processor (22:00 in the scheduled jobs) classifies later. Two-step capture beats one-step organization every time.
• /wrap is the single highest-leverage habit. End every Claude session with /wrap — silently files decisions, insights, tasks. Without it, every conversation is potentially lost data. With it, every chat auto-deposits.
• Refuse to invent. /decision asks for rationale if missing rather than fabricating. /recall says "no matching rows" rather than confidently making up an answer.
• The system improves the system. Scheduled synthesis (mornings, mini-briefings, weekly rollups) compounds the value of captured signal. Hourly logs alone aren't valuable; hourly logs + nightly reconstruction + weekly digest are.

License

MIT. See LICENSE.

Provenance

Built solo over a single intensive session in May 2026 with Claude assistance throughout. Heavy influences:

• Tiago Forte (PARA / Building a Second Brain)
• Brian Petro (Smart Connections / Obsidian-AI ecosystem)
• Khoj.dev (open-source self-hostable AI second brain)
• The "Claude Code + Obsidian" Medium/Substack community

If you fork this, let me know what you build with it.