Fragments

Setup Check

1. Read ~/.config/fragments.json (Windows: %USERPROFILE%\.config\fragments.json).
2. If file missing → first install. Detect current platform, read the matching setup guide:
   • Claude Code → references/setup-claude-code.md
   • OpenCode → references/setup-opencode.md
   • OpenClaw → references/setup-openclaw.md
3. If file exists → verify MCP is configured. If incomplete → read the matching setup guide.
4. All good → proceed to normal usage.

Platform Detection

Detect the current platform by checking for platform-specific markers:

Modes

memo — Full Lifecycle Management

Create, search, update, delete, and comment on memos via MCP tools.

Workflows:

• Create & dedup → references/memo-capture.md
• Update & delete → references/memo-capture.md#lifecycle
• Comments → references/memo-comments.md

Write operations require user confirmation before calling.

daily-log — Daily Work Journal

One structured log per user per day. Content follows .plan format enforced by the Memos server.

Format rules, diff-merge logic, and hook trigger workflow: → references/daily-log.md

search — Semantic Search

Server-side full-text retrieval via MCP, optional client-side TF-IDF + LSA rerank for semantic/fuzzy queries.

Pipeline details and tuning parameters: → references/search-strategy.md

Retrieval Strategy

Data volume can be large. Always prefer targeted retrieval over bulk listing.

Memos

1. Search first: memos_search_memos(query=...) — use when the user has any intent, keyword, or topic. Returns bounded results.
2. Get by ID: memos_get_memo(name=...) — use when you already know the memo name. Expand full content only for shortlisted results.
3. List as fallback: memos_list_memos(page_size=10) — use only for explicit "show recent" requests. Always set a small page_size.
4. Client-side rerank: pipe search results through scripts/fragments_search.py for semantic ranking when server-side results need refinement.

Comments

• List comments: memos_list_memo_comments(name=...) — retrieve all comments on a memo. Comments inherit the parent memo's visibility.

Daily Logs

1. Get by date: memos_get_daily_log(date=YYYY-MM-DD) — single log lookup. Pass creator="users/{id}" to view another user's log (PROTECTED visibility).
2. List with date range: memos_list_daily_logs(start_date, end_date, page_size=10) — use only for explicit "show this week/month" requests. Always bound the range.

Tags

• memos_list_tags — lightweight, use to discover available tags for filtering.

No read operations require user confirmation.

Write Operations

All write operations require explicit user confirmation before calling. Read operations need no confirmation. Never echo PAT tokens to the conversation.

Memo Writes

Daily Log Writes

• memos_save_daily_log(date=..., content=...) — full replacement save. Always include complete content (existing + new lines).

Hook Workflow (Passive Trigger)

When triggered by agent task completion:

1. Assess whether this session performed meaningful work. Skip if trivial.
2. Call memos_get_daily_log for today's date.
3. Format new entries in .plan style.
4. Diff against existing content. Skip if no new information.
5. Long-form content → suggest creating a memo first, reference in daily log.
6. Show user the full merged log (existing + new). Wait for confirmation.
7. Call memos_save_daily_log with complete content (full replacement).