agentleFS
markmhendricksonmarkmhendrickson/neotoma/.claude/skills/store_neotoma/SKILL.md

store_neotoma

Skill38 starsChanged 2 months agoMITView on GitHub

store-neotoma

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 5 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If user confirms ("proceed", "confirm", "yes", "go ahead", or equivalent): proceed to Phase 1.

    line 74
  2. Distinctive:

    If user provides input: apply it to preview and/or payloads:

    line 75
  3. Distinctive:

    Add or remove derived entities.

    line 78
  4. Very specific:

    Use store_structured (or equivalent MCP action).

    line 95
  5. Distinctive:

    Create image/media entity if file is an image.

    line 111
  6. Distinctive:

    If EMBEDS fails (known issue), log and continue.

    line 113
  7. Distinctive:

    If the user gave no "how to store" input, skip this step.

    line 123

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- Source: .cursor/skills/store-neotoma/SKILL.md -->

store-neotoma

Purpose

Define the workflow for reviewing chat, building a Neotoma store preview, and executing storage after user confirmation. Neotoma is the only data store; there is no Parquet migration phase.

Canonical location: foundation/.cursor/skills/store-neotoma/SKILL.md (foundation git submodule). Consumer repos may symlink or copy this into .cursor/skills/store-neotoma/ via setup_cursor_copies / setup_cursor_rules.

Scope

Applies when the user asks to store the current chat in Neotoma. Covers preview, user revisions, confirmation, storage, and relationships. Excludes one-off store operations without preview.

Reviews the current chat conversation, builds a preview of records to store in Neotoma, waits for user confirmation (or revision input), then stores conversation, two agent_message entities per logical turn (role: "user" and role: "assistant"), each with PART_OF → conversation — the canonical shape from Neotoma MCP live chat instructions — plus attachments.

Preview-before-execute: On first run, this workflow MUST preview what will be stored and MUST NOT execute storage until the user confirms. User input (corrections, scope changes, exclusions) MUST be applied to revise the preview.

Prerequisites

  • Chat transcript available in agent context (user and agent messages).
  • Neotoma MCP available.
  • Load .claude/rules/conversation_tracking.mdc and .claude/rules/neotoma_access_policy.mdc for entity schemas and access rules. conversation_tracking defines dual-message + PART_OF; do not use merged role_user/role_agent on a single agent_message.

Phase 0: Preview (MANDATORY — Execute First)

Step 0.1 — Extract and build preview

Parse all user and agent messages in the conversation. For each logical turn (user message + following assistant reply):

  • User row (preview + store): entity_type: agent_message, role: "user", content = exact user text, turn_key (stable per turn), optional turn_number (1-based), timestamp, files_modified, tools_used, platform, model, neotoma_operations (inferred from the turn).
  • Assistant row (preview + store): entity_type: agent_message, role: "assistant", content = exact assistant text shown in chat, turn_key e.g. same base + :assistant, optional same turn_number / timestamp for sorting.
  • Topics: extract from user questions, entity types discussed, file paths, domain keywords (finance, admin, health, work).
  • Decisions: extract when agent states an approach, user confirms a choice, or implementation strategy is chosen.
  • Action items: tasks to create, follow-ups mentioned.
  • files_modified: file paths from tool calls, @-mentions, or explicit file references (typically attributed to the user message for that turn).
  • neotoma_operations: inferred from agent tool-call patterns (store_structured, correct, create_relationship).

Identify attachments. All of the following must be included:

  • User-uploaded files (images, screenshots, files attached or pasted in any message, including turn 1). Use whatever path or content the platform provides.
  • @-mentioned file paths.
  • Attachment references and file URLs in message text.

Build preview structure:

  • Conversation: full payload with every property and exact value to be stored (see Step 0.2).
  • Messages: two exact agent_message payloads per turn (user and assistant), each with every property and exact value to be stored, plus distinct idempotency_key / turn_key per row. Include PART_OF targets (conversation entity_id after conversation is created).
  • Attachments: list of files to store with path, type, and any store payload (file_path or file_content).
  • Derived entities (optional): tasks, contacts, events, transactions, notes, or other entity types the turn implies. Show exact raw payloads for user approval.

Step 0.2 — Display preview

Show structured preview to the user with clear sections. Include tables with the exact properties and exact raw values of every structured object that will be sent to Neotoma, so the user can approve precise payloads before proceeding.

Required sections:

  1. Conversation entity (exact payload).
  2. Agent_message entities (exact payloads — pairs per turn: user then assistant).
  3. Attachments (all user-uploaded files, @-mentioned paths, file URLs).
  4. Relationships to create.
  5. Derived entities (exact payloads for any non-chat entities implied by the conversation).

End the preview with:

  • Confirm to proceed, or provide input to revise.
  • Revisions can include exclusions, title/topics changes, and "how to store" preferences (field names, exclusions, formats).

Step 0.3 — Wait for user response

  • If user confirms ("proceed", "confirm", "yes", "go ahead", or equivalent): proceed to Phase 1. If the user previously provided "how to store" input, retain it for post-store neotoma-learn.
  • If user provides input: apply it to preview and/or payloads:
    • Exclude turns (e.g. "skip turn 3").
    • Change title or topics.
    • Add or remove derived entities.
    • Correct any field.
    • How to store (e.g. "use conversation_id without date prefix", "store topics as JSON string"). Do not request reverting to merged single-row role_user/role_agent; dual messages are canonical.
  • Re-display the revised preview (including updated exact payload tables), then wait again.
  • Repeat until user confirms.

Phase 1: Storage (After Confirmation)

Step 1.1 — Create conversation entity

Generate conversation_id if not yet final. Store via Neotoma MCP:

  • entity_type: conversation
  • conversation_id, title, turn_count, start_timestamp, last_updated
  • topics, decisions, action_items
  • platform: cursor, status: active, summary

Use store_structured (or equivalent MCP action).

Step 1.2 — Create agent_message entities per turn (dual rows)

For each turn (respecting exclusions from preview), create two stored messages linked to the same conversation:

  1. User message: entity_type: agent_message, role: "user", content (full text), turn_key, optional turn_number, timestamp, files_modified, tools_used, platform, model, neotoma_operations as previewed.
  2. Assistant message: entity_type: agent_message, role: "assistant", content (full text), turn_key (distinct from user row), optional same turn_number / timestamp.

Store via Neotoma MCP (store_structured), batching multiple entities and relationships in one request when supported. For each row, ensure PART_OF from that agent_message → conversation (conversation entity_id from Step 1.1 response). Use distinct idempotency_key values per message (e.g. suffix -user / -assistant per turn).

Step 1.3 — Handle attachments

For each file in the attachments list with an accessible path:

  • Store file via Neotoma using file_path (or file_content if required).
  • Create image/media entity if file is an image.
  • Attempt create_relationship(EMBEDS, user_agent_message_entity_id, file_entity_id) for attachments on the user turn (or conversation-level link if turn-level linking is unavailable).
  • If EMBEDS fails (known issue), log and continue.

Step 1.4 — Create relationships

  • For each agent_message (user and assistant): create_relationship(PART_OF, agent_message_entity_id, conversation_entity_id) if not already created in the same batched store_structured call.
  • For tasks, contacts, projects, execution plans, and other discussed entities: conversation --[REFERS_TO]--> entity, or agent_message --[REFERS_TO]--> entity for turn-level links.

Step 1.5 — If user provided "how to store" input: invoke neotoma-learn skill

  • If during Phase 0 the user provided input on how to store objects (field renames, exclusions, format preferences), after Phase 1 invoke the neotoma-learn skill with that input as the scenario/description (for example "When storing conversation from /store_neotoma: use conversation_id without date prefix"). Do not use neotoma-learn to undo dual-message storage; that shape is canonical.
  • If the user gave no "how to store" input, skip this step.

Output and Reporting

After execution, report:

  • Storage summary: conversation_id, agent_message count (expect ~2× turn count when both sides exist), attachments stored, relationship count, derived entity count.
  • Per .claude/rules/persistence.mdc, show stored entities via retrieve/list observation actions where relevant.
  • Render the mandatory 🧠 Neotoma turn report per .claude/rules/neotoma_turn_lifecycle.mdc.

Error Handling

  • Neotoma MCP failures: retry once, then report and continue where possible.
  • EMBEDS relationship failure: log and continue.

References

  • execution/scripts/migrate_neotoma_chat_dual_messages.py — One-off migration for legacy merged role_user/role_agent rows and inverted PART_OF edges; use --cli with the neotoma binary when HTTP bearer is rejected (dry-run by default, --execute to apply). Path is relative to repos that include execution/ (e.g. ateles); omit or locate equivalent in other layouts.
  • .claude/rules/conversation_tracking.mdc — Entity model and fields.
  • .claude/rules/neotoma_access_policy.mdc — Canonical Neotoma-only access rules.
  • .claude/rules/neotoma_turn_lifecycle.mdc — Turn lifecycle and turn report contract.
  • .claude/rules/confirmation_requirements.mdc — Preview/confirm pattern.
  • .cursor/skills/neotoma-learn/SKILL.md — Update Neotoma MCP instructions after user provides "how to store" input (repo-local skill where present; not bundled in foundation-only checkouts).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.