Initialize the OpenLMlib knowledge base. Call this ONCE before using any other tools.

AUTOMATIC TRIGGERS - Call this when:

• First time using OpenLMlib on a new machine or project

• You get database errors suggesting the database doesn't exist

• User asks to set up or initialize OpenLMlib

DO NOT CALL for:

• Normal tool usage (database already exists)

• Each session start (initialization is permanent)

This creates the SQLite database, vector index, and required directories. Safe to call multiple times - will skip if already initialized.

Save critical research findings, discoveries, and insights to persistent library.

AUTOMATIC TRIGGERS - Call this when:

• You discover important factual information during research

• You complete an analysis with actionable insights

• You find evidence supporting or refuting a hypothesis

• You learn something new about the codebase or project

• User shares important information that should be remembered

DO NOT CALL for:

• Temporary working notes

• Process updates or progress reports

• Conversation summaries

• Tool execution results (unless they contain novel insights)

WORKFLOW POSITION: Call after discovering insights, before ending session. Save findings as you go - don't wait until the end.

READ-BEFORE-WRITE: This tool automatically checks for similar findings before saving. If a very similar finding exists (similarity > 0.90), it will be returned as a suggestion instead of saving a duplicate. Consider updating the existing finding instead.

SESSION AWARENESS: For best results, use start_research or session_start before saving findings. This enables automatic context injection and session-based knowledge tracking. If no active session is detected, a warning will be returned.

CONFIRMATION TIER: WRITE OPERATION - Requires confirm=True. This creates persistent data. Set confirm=true for final saves, confirm=false for drafts.

PARAMETERS:

• project: Project name for categorization (required)

• claim: The finding/insight text (required) - be specific and actionable

• confidence: Confidence level 0.0-1.0 (default: 0.8). Use 0.9 for definitive findings, 0.7 for tentative, 0.5 for hypotheses

• evidence: Supporting evidence strings (optional) - quotes, data points, references

• reasoning: Your reasoning behind the finding (optional but recommended)

• caveats: Limitations or cave (optional)

• tags: Tags for categorization (optional) - use consistent tags

• confirm: Must be True to save (safety gate). Use False for drafts.

TIP: If a similar finding already exists, consider updating it instead of creating a duplicate. Use search_findings first to check for duplicates.

List recent findings in the library. Use for browsing, not targeted search.

AUTOMATIC TRIGGERS - Call this when:

• User asks to see all findings or browse the library

• You want to get a sense of what's stored in the library

• Checking library contents after initialization

FOR TARGETED SEARCH, use search_findings or retrieve_findings instead.

PARAMETERS:

• limit: Max findings to return (default: 50, max: 200)

• offset: Offset for pagination (default: 0)

Get a specific finding by its ID.

AUTOMATIC TRIGGERS - Call this when:

• You have a finding_id from search results or list

• You need the full details of a specific finding

• User references a specific finding ID

Use search_findings first to find the ID if you don't have it.

Search findings using keyword (FTS5) search. Fast, exact keyword matching.

AUTOMATIC TRIGGERS - Call this when:

• Looking for findings containing specific keywords

• You know the exact terms used in a finding

• Quick lookup of stored knowledge

WORKFLOW POSITION: Use FIRST for targeted keyword search. If results are insufficient, try retrieve_findings for semantic search that finds related concepts.

CONFIRMATION TIER: READ OPERATION - No confirmation needed. Safe to call freely.

SEARCH TIPS: Use specific keywords. FTS5 supports boolean operators:

• "python web framework" finds all three words

• "python AND web" finds both

• "python OR javascript" finds either

PARAMETERS:

• query: Search query (keyword(s))

• limit: Max results (default: 10)

Run intelligent retrieval combining semantic similarity and keyword matching.

AUTOMATIC TRIGGERS - Call this when:

• Keyword search (search_fts) didn't find relevant results

• Looking for findings related to a concept or topic

• You need the most relevant findings for a research question

• Broad exploration of what knowledge exists

WORKFLOW POSITION: Use AFTER search_fts returns insufficient results. This tool automatically combines semantic (meaning-based) and lexical (keyword) search.

CONFIRMATION TIER: READ OPERATION - No confirmation needed. Safe to call freely.

PARAMETERS:

• query: Search query (required) - describe what you're looking for

• project: Filter by project name (optional)

• tags: Filter by tags (optional)

• confidence_min: Minimum confidence 0.0-1.0 (optional) - filter low-confidence findings

• final_k: Number of results to return (optional, default: 10)

ADVANCED: semantic_k and lexical_k control how many candidates are fetched before reranking. Usually not needed - use final_k instead.

Retrieve findings and return them in a sanitized format safe for LLM context.

AUTOMATIC TRIGGERS - Call this when:

• You need to inject findings into your context for reasoning

• Building a knowledge base context for analysis

• You want findings formatted safely without injection risks

DIFFERENCE from retrieve_findings: This returns a sanitized context block optimized for safe inclusion in LLM prompts. Use retrieve for raw data.

ERROR RECOVERY: If this returns no results, try search_findings for keyword-based search instead - the semantic query may not match any findings.

PARAMETERS:

• query: Search query (required)

• project: Filter by project (optional)

• tags: Filter by tags (optional)

• confidence_min: Minimum confidence (optional)

• final_k: Number of results (optional, default: 10)

Search findings using both semantic similarity and keyword matching. Automatically combines both approaches for best results.

AUTOMATIC TRIGGERS - Call this when:

• You need to search for existing knowledge

• Starting research or looking for past findings

• Not sure whether to use keyword or semantic search

This tool handles routing internally - no need to choose between search_findings and retrieve_findings.

For broad exploration, use general query terms. For specific facts, use exact phrases or keywords.

CONFIRMATION TIER: READ OPERATION - No confirmation needed. Safe to call freely.

PARAMETERS:

• query: Search query (required) - keywords or natural language

• limit: Max results (default: 10)

Returns combined results from both FTS keyword search and semantic retrieval.

Delete a finding by ID. DESTRUCTIVE - use with caution.

AUTOMATIC TRIGGERS - Call this when:

• User explicitly asks to delete a specific finding

• A finding is clearly incorrect or outdated

DO NOT CALL for:

• Cleaning up duplicates (update instead)

• Without explicit user confirmation

CONFIRMATION TIER: DESTRUCTIVE - Requires explicit confirm=True with user approval. This operation is PERMANENT and cannot be undone. Always warn the user before calling.

SAFETY: Requires confirm=True to prevent accidental deletion. The finding is permanently removed.

PARAMETERS:

• finding_id: ID of the finding to delete (required)

• confirm: Must be True to delete (safety gate)

Check OpenLMlib database and vector index health.

AUTOMATIC TRIGGERS - Call this when:

• Debugging tool errors or unexpected behavior

• User asks about the system status

• Verifying initialization succeeded

Returns database size, finding count, vector index status.

Run retrieval evaluation metrics on a test dataset. For developers testing improvements.

AUTOMATIC TRIGGERS - Call this when:

• Evaluating retrieval quality after configuration changes

• Running the evaluation pipeline

• Measuring recall/precision of the search system

This is a development/evaluation tool, not needed for normal usage.

PARAMETERS:

• dataset_path: Path to JSON file with test queries (default: config/eval_queries.json)

• final_k: Number of results per query to evaluate (default: 10)

Begin a complete research session with automatic context loading. COMPOSITE TOOL.

AUTOMATIC TRIGGERS - Call this when:

• Starting any research task or investigation

• User asks to "research" or "look into" something

• Beginning work on a new topic area

This replaces calling session_start + search_findings separately. It handles session creation, context injection, and initial finding search in one step.

WORKFLOW: After this returns, proceed with research and call save_finding for important discoveries. When done, call session_end.

PARAMETERS:

• session_id: Unique session identifier for this research session

• topic: What you'll be researching (used to find relevant past context and search findings)

• user_id: Optional user/agent identifier

• limit: Max past observations to inject (default: 50)

Returns session info, injected context, and any existing findings on the topic.

Gracefully end the current session with automatic knowledge preservation. COMPOSITE TOOL.

AUTOMATIC TRIGGERS - Call this when:

• User indicates work is done ("done", "finished", "ending session")

• Research or analysis is complete

• About to start unrelated work

This combines: session_end (saves summary) + optional artifact export. ALWAYS call this when user indicates work is done to prevent knowledge loss.

WORKFLOW POSITION: Last tool in any research/analysis workflow.

PARAMETERS:

• session_id: The session to end (track from start_research or session_start)

• export_to_library: If True, also search for recent findings to persist (default: True)

• project: Project name for any exported findings (optional)

Returns session end status and export results.

Quick check if relevant context exists before starting work. CONVENIENCE TOOL.

AUTOMATIC TRIGGERS - Call this at the start of ANY new task to determine whether you have existing knowledge to build upon.

This is a convenience wrapper around search_fts that returns a simple yes/no with relevant finding count and top topics.

WORKFLOW POSITION: First tool to call when starting any task.

CONFIRMATION TIER: READ OPERATION - No confirmation needed. Safe to call freely.

PARAMETERS:

• query: What you're about to work on

• project: Filter by project (optional)

Returns: {has_context: bool, finding_count: int, top_findings: []}

Convenience wrapper for saving findings with automatic confidence scoring.

AUTOMATIC TRIGGERS - Call this whenever you discover something important. Use when you think 'this is important' or 'this should be remembered'.

Automatically sets confidence based on claim language:

• 0.9 for definitive findings (factual, certain claims)

• 0.7 for tentative findings (contains words like 'might', 'possibly', 'appears', 'suggests')

• Uses provided confidence if explicitly set

READ-BEFORE-WRITE: This tool automatically checks for similar findings before saving. If a very similar finding exists, it will be returned as a suggestion.

CONFIRMATION TIER: WRITE OPERATION - Requires confirm=True. This creates persistent data. Set confirm=true for final saves.

PARAMETERS:

• project: Project name (required)

• claim: The finding text (required)

• confidence: Optional override (default: auto-scored 0.9 for definitive, 0.7 for tentative)

• evidence: Supporting evidence (optional)

• reasoning: Your reasoning (optional but recommended)

• caveats: Limitations or cave (optional)

• tags: Tags for categorization (optional)

• confirm: Must be True to save (safety gate)

Get help about all OpenLMlib MCP tools or a specific tool.

Call this with no arguments to see all available tools organized by category. Call with a specific tool_name to get detailed usage instructions.

Args: tool_name: Optional specific tool name to get help for (e.g., 'save_finding', 'create_session')

Returns: Dict with tool descriptions and usage information

Get tool usage analytics and optimization metrics. For developers and optimization tracking.

AUTOMATIC TRIGGERS - Call this when:

• Measuring optimization effectiveness after tool description changes

• Tracking automatic vs explicit tool call rates

• Monitoring parameter hallucination rates

• Evaluating tool selection accuracy

• Running A/B tests on tool descriptions

Returns metrics for:

• Automatic call rate (% of calls the model made without explicit instruction)

• Tool selection accuracy (% of correct tool choices)

• Parameter hallucination rate (% of parameters that needed correction)

• Workflow completeness (% of workflow steps completed)

• Per-tool usage breakdown

PARAMETERS:

• days: Look back N days (default: 7)

• tool_name: Filter by specific tool (optional)

This is a development/evaluation tool, not needed for normal usage.

Start a new session and automatically inject relevant context from past sessions.

AUTOMATIC TRIGGERS - Call this when:

• Beginning a new work session or conversation

• User starts a new conversation about ongoing work

• You need context from previous sessions before starting work

ALWAYS CALL THIS at the start of any work session - it prevents starting work without historical context. This loads knowledge from all previous sessions.

WORKFLOW POSITION: First tool to call when starting work.

PARAMETERS:

• session_id: Unique identifier for this session (generate a unique ID like UUID or timestamp-based)

• query: What this session will focus on - used to find relevant past context (optional but recommended)

• limit: Max past observations to inject (default: 50, reduce for focused sessions)

• user_id: Optional user/agent identifier

Returns context block with relevant past observations (compressed for efficiency).

End the current session and trigger automatic summarization to persist knowledge.

AUTOMATIC TRIGGERS - Call this when:

• User indicates they're done with current work ("done", "finished", "ending session")

• Session goal has been achieved

• About to start unrelated work

• You're wrapping up a task or research phase

ALWAYS CALL THIS when ending work to ensure session knowledge is not lost. This automatically generates a compressed summary of all observations.

WORKFLOW POSITION: Last tool to call when finishing work.

PARAMETERS:

• session_id: The session to end (track this from session_start)

Log an observation from tool execution to build session memory.

AUTOMATIC TRIGGERS - Call this when:

• A tool execution produces important or surprising results

• You want to remember what happened during the session

• Building up context for the end-of-session summary

This captures tool outputs for future memory retrieval. Call this after significant tool executions to build session memory.

WORKFLOW POSITION: Call after important tool executions throughout the session. The observation will be compressed and summarized for future retrieval.

PARAMETERS:

• session_id: Active session identifier (from session_start)

• tool_name: Tool that was executed (e.g., "web_search", "read_file")

• tool_input: What was passed to the tool

• tool_output: What the tool returned

NOTE: Don't log every single tool call - only significant ones with novel insights.

Layer 1: Lightweight search of memory index (~75 tokens/result). Fast metadata search.

AUTOMATIC TRIGGERS - Call this when:

• You need to identify which memories might be relevant

• Before fetching full observations (to filter first)

• Searching for observations by tool name, type, or session

Returns compact metadata for filtering. Use this FIRST to identify relevant memories, then use memory_timeline or get_observations for details.

SEARCH STRATEGY: Use specific keywords. Filter by tool_name, obs_type, or session_id.

PARAMETERS:

• query: Search query

• limit: Max results (default: 50)

• filters: Optional filters like {"tool_name": "web_search", "session_id": "..."}

Layer 2: Get chronological context for memory IDs (~200 tokens/result).

AUTOMATIC TRIGGERS - Call this when:

• You have observation IDs from search_memory

• You need to understand the sequence of events

• Understanding how observations relate to each other over time

Returns narrative flow around observations. Use AFTER search_memory to understand sequence. Provides timeline context for how observations relate to each other.

PARAMETERS:

• ids: List of observation IDs from search_memory

• window: Time window for context around each observation (default: "5m")

[DEPRECATED] Layer 3: Get full details for specific memory IDs. Use query_memory instead.

AUTOMATIC TRIGGERS - Call this when:

• You have specific observation IDs and need complete details

• After filtering with search_memory and memory_timeline

• You need the full raw data of specific observations

Returns complete observation data. Use ONLY for explicitly selected relevant items. This is the most expensive layer - filter first with search_memory.

PARAMETERS:

• ids: List of observation IDs from search_memory or memory_timeline

Adaptive auto-expanding retriever for memory. REPLACES search_memory.

AUTOMATIC TRIGGERS - Call this when:

• You need to search for observations from past sessions

• You want to retrieve context about a specific topic from memory

This tool automatically performs a 3-layer progressive retrieval in a single step. It runs a fast search, expands high-confidence hits into full observations, and provides chronological context for the periphery.

PARAMETERS:

• query: Search query

• limit: Max results to fetch internally (default: 20)

• filters: Optional filters like {"tool_name": "web_search", "session_id": "..."}

Auto-inject relevant context from past sessions at any point during work.

AUTOMATIC TRIGGERS - Call this when:

• You need a refresher on past work mid-session

• Starting work on a new subtask and want relevant context

• User asks "what have we learned about X previously?"

Retrieves up to 50 relevant observations from previous sessions. Unlike session_start (which auto-injects), you can call this mid-session.

WORKFLOW POSITION: Call anytime you need past context, not just at session start.

PARAMETERS:

• session_id: Current session ID

• query: What you want context about (optional - uses session focus if not provided)

• limit: Max observations to inject (default: 50)

• user_id: Optional user/agent identifier used to isolate memory context

Get a synthesized recap of recent session knowledge (~150-250 tokens). Structured, not raw.

AUTOMATIC TRIGGERS - Call this FIRST when:

• Starting work to understand what happened in past sessions

• User asks "what have we been working on?"

• You want to see files touched, decisions made, next steps

Returns STRUCTURED knowledge: files touched, decisions made, next steps, conventions discovered — NOT raw tool outputs.

If you need more details on a specific topic AFTER reading the recap, call topic_context with a topic from the recap.

PARAMETERS:

• session_id: Optional specific session to recap (default: recent sessions)

• limit: Max recent sessions to recap (default: 3)

Get detailed context about a specific topic from past sessions (~500-800 tokens). Deep dive.

AUTOMATIC TRIGGERS - Call this AFTER session_recap when:

• You need deep understanding of a specific topic

• User asks about a specific area like "what do we know about storage?"

• Example topics: 'storage', 'privacy', 'MCP', 'compression', 'caveman', 'session_manager', or any file name/feature from the recap

Returns detailed files, decisions, architecture notes, and conventions related to the topic — not just compressed tool outputs.

PARAMETERS:

• topic: Topic to get detailed context about (e.g., 'storage', 'privacy')

• session_id: Optional specific session to search (default: all sessions)

Auto-ingest session activity from git history. NO manual logging needed!

Create a new collaboration session for multi-agent research.

AUTOMATIC TRIGGERS - Call this when:

• Starting a new multi-agent research task

• User asks to set up a collaboration session

• You need to coordinate work across multiple agents

WORKFLOW POSITION: First tool in any collaboration workflow.

PARAMETERS:

• title: Short descriptive title for the session

• task_description: Detailed description of the research task

• plan: Optional list of task dicts (step, task, assigned_to) - recommended for structured work

• rules: Optional session rules (max_agents, require_assignment)

• created_by: Your agent identifier (default: "orchestrator")

After creation, use join_session for agents to join, then send_message to assign tasks.

Join an existing collaboration session as an agent.

AUTOMATIC TRIGGERS - Call this when:

• You've been assigned work in a session

• You need to participate in an active collaboration

• Starting work as a worker or specialist in a multi-agent setup

WORKFLOW POSITION: Call after session is created and you have the session_id.

PARAMETERS:

• session_id: ID of the session to join

• model: Your model identifier (e.g., 'gpt-codex', 'gemini-pro')

• capabilities: Optional list of your capabilities (e.g., ['research', 'code_analysis'])

After joining, read the session_context above to understand current state, then use read_messages to check for new messages.

List collaboration sessions. Browse sessions you've participated in.

AUTOMATIC TRIGGERS - Call this when:

• User asks to see their sessions

• You want to find a specific session to rejoin

• Checking what sessions are active

FOR SESSION DETAILS, use session_context after finding the session_id.

PARAMETERS:

• status: Filter by status - "active", "paused", "terminated" (canonical end), or "completed" (legacy ended sessions)

• limit: Max sessions to return (default: 20, max: 100)

Get the current state of a collaboration session - tasks, agents, and session state.

AUTOMATIC TRIGGERS - Call this when:

• You need to see the task list and assignments

• Checking which agents are in the session

• Reviewing session metadata (status, created_at, etc.)

DIFFERENCE from session_context: This returns raw structured data (tasks, agents, state dict). Use get_session_context for a formatted narrative view.

PARAMETERS:

• session_id: ID of the session

• agent_id: Your agent ID (must belong to the session)

Update the session state. Orchestrator only. The only way to modify session state.

AUTOMATIC TRIGGERS - Call this when:

• You need to record progress updates

• Setting the current phase of work

• Storing session metadata (current step, active agents, etc.)

ONLY the orchestrator can call this. State is versioned with optimistic concurrency to prevent conflicts. If update fails, retry with latest state.

PARAMETERS:

• session_id: Target session

• state: New state dict (will be merged with existing state)

• orchestrator_id: The orchestrator's agent ID (for authorization)

Send a message to a collaboration session. Core communication tool.

AUTOMATIC TRIGGERS - Call this when:

• Assigning work to an agent (msg_type="task")

• Returning findings or completed work (msg_type="result")

• Asking for clarification (msg_type="question")

• Responding to a question (msg_type="answer")

• Providing progress updates (msg_type="update")

• Marking a task as done (msg_type="complete")

MESSAGE TYPES:

• task: Assign work to an agent

• result: Return findings or completed work

• question: Ask for clarification

• answer: Respond to a question

• ack: Acknowledge a message

• update: Progress update

• artifact: Reference a saved artifact

• complete: Mark a task as done

• system: System notification (auto-generated)

WORKFLOW POSITION: Use throughout the session for all agent communication.

PARAMETERS:

• session_id: Target session

• msg_type: Type of message (see above)

• content: Message content

• to_agent: Target agent ID (or None for broadcast)

• from_agent: Your agent ID (required)

• metadata: Optional metadata dict

Read new messages from a session. Returns only unseen messages (offset-tracked).

AUTOMATIC TRIGGERS - Call this when:

• Checking for new messages after sending a response

• Looking for task assignments or answers to your questions

• Periodic status check during active collaboration

DIFFERENCE from poll_messages: This returns immediately without waiting. Use poll_messages for blocking waits in autonomous agent loops.

WORKFLOW POSITION: Call after sending messages, between work steps.

PARAMETERS:

• session_id: Session to read from

• agent_id: Your agent ID (required for authorization and offset tracking)

• limit: Max messages to return (default: 50, max: 200)

• msg_types: Filter by message types like ["task", "answer"] (optional)

• from_agent: Filter by specific sender (optional)

Wait for and read new messages from a session. AUTONOMOUS LOOP tool for agent communication.

AUTOMATIC TRIGGERS - Call this when:

• You're running an autonomous agent loop

• Waiting for other agents to complete work

• Need real-time collaboration without human intervention

This tool BLOCKS until new messages arrive or the timeout expires. It is the primary mechanism for agents to run continuous collaboration.

USAGE PATTERN FOR AUTONOMOUS AGENTS: 1. Call poll_messages(session_id, agent_id, timeout=30) 2. Process any returned messages 3. Send responses via send_message 4. Repeat from step 1 until the session is complete

WORKFLOW POSITION: Main loop tool for autonomous agents.

PARAMETERS:

• session_id: Session to monitor

• agent_id: Your agent ID

• timeout: Max seconds to wait (default: 30, 0 = no wait)

• limit: Max messages to return (default: 50)

• msg_types: Filter by message types (optional)

• from_agent: Filter by sender (optional)

Read the last N messages from a session. Quick status check without offset tracking.

AUTOMATIC TRIGGERS - Call this when:

• You just joined and want to see recent activity

• Quick glance at what's happening without tracking offsets

• Checking session state before full context load

DIFFERENCE from read_messages: This does NOT track your read offset and always returns the most recent N messages regardless of what you've seen. Use read_messages for tracking unseen messages.

PARAMETERS:

• session_id: Session to read from

• agent_id: Your agent ID (must belong to the session)

• n: Number of messages (default: 20, max: 100)

Read messages in a specific sequence range. Zoom into a conversation section.

AUTOMATIC TRIGGERS - Call this when:

• You need context from a specific point in the conversation

• A message references an earlier seq number

• You want to review a specific exchange between agents

DIFFERENCE from read_messages: This reads a specific range by sequence numbers, not just "new" messages. Use for targeted context retrieval.

PARAMETERS:

• session_id: Session to read from

• start_seq: Starting sequence number (inclusive) - get from message metadata

• end_seq: Ending sequence number (exclusive) - max range is 500 messages

• agent_id: Your agent ID (must belong to the session)

Search session messages by keyword. FTS5 full-text search across all messages.

AUTOMATIC TRIGGERS - Call this when:

• Looking for a specific topic, decision, or finding mentioned earlier

• You don't know the sequence number but remember keywords

• Checking if a topic has been discussed in the session

SEARCH TIPS: Use simple keywords. FTS5 supports: "word1 word2" (AND), "word1 OR word2". Avoid complex syntax - use plain phrases.

PARAMETERS:

• session_id: Session to search

• pattern: Search term (use simple keywords)

• agent_id: Your agent ID (must belong to the session)

• limit: Max results (default: 50, max: 100)

• msg_types: Filter by message types like ["result", "artifact"] (optional)

Get a compiled context view of the session. PRIMARY tool for understanding session state.

AUTOMATIC TRIGGERS - Call this when:

• Joining a session and you need to understand current state

• Before starting work to see what's been done

• After being assigned a task to understand context

• Whenever you're unsure about session status

This is the GO-TO tool for session understanding. Returns summary + recent messages

• state + tasks + artifacts in a formatted view optimized for context windows.

WORKFLOW POSITION: Call after joining, before starting work, and periodically.

PARAMETERS:

• session_id: Session to get context for

• agent_id: Your agent ID

• max_messages: Max recent messages to include (default: 20)

Save a research artifact (finding, analysis, summary) to the session.

AUTOMATIC TRIGGERS - Call this when:

• You complete a significant analysis or research summary

• You've written important code or documentation

• You want to save a detailed analysis (beyond a simple message)

• Completing a major deliverable

Use this for SIGNIFICANT work products, not for inline messages. Artifacts are stored as files with metadata indexed in SQLite.

WORKFLOW POSITION: Call after completing substantial work.

PARAMETERS:

• session_id: Target session

• title: Descriptive title for the artifact

• content: Full artifact content (markdown recommended)

• created_by: Your agent ID

• artifact_type: Type like 'research_summary', 'analysis', 'code', 'data'

• tags: Tags for categorization

• shared: If True, save to shared directory (default: False)

List artifacts in a session. Browse saved work products, analyses, and summaries.

AUTOMATIC TRIGGERS - Call this when:

• Checking what work has been saved in the session

• Looking for a specific analysis or report

• Before creating a new artifact to avoid duplicates

FOR ARTIFACT CONTENT, use get_artifact after finding the artifact_id.

PARAMETERS:

• session_id: Target session

• agent_id: Your agent ID (must belong to the session)

• created_by: Filter by creator agent (optional) - "show artifacts by agent X"

• artifact_type: Filter by type like "research_summary", "analysis", "code" (optional)

Get the full content of a specific artifact. Retrieve saved analysis or report.

AUTOMATIC TRIGGERS - Call this when:

• You have an artifact_id from list_artifacts or a message reference

• Need to review another agent's completed work

• Reading detailed analysis that was saved as an artifact

WORKFLOW POSITION: Call after finding the artifact_id from list_artifacts or messages.

PARAMETERS:

• session_id: Session containing the artifact

• artifact_id: ID of the artifact (e.g., "art_abcdef12")

• agent_id: Your agent ID (must belong to the session)

Search artifact content by keyword. Find saved work by topic or term.

AUTOMATIC TRIGGERS - Call this when:

• Looking for artifacts mentioning a specific topic

• Need to find prior analysis on a subject

• Searching across all saved work products in the session

PARAMETERS:

• session_id: Session to search

• pattern: Search term (use simple keywords)

• agent_id: Your agent ID (must belong to the session)

• created_by: Filter by creator agent (optional)

Leave a collaboration session gracefully. Clean exit for an agent.

AUTOMATIC TRIGGERS - Call this when:

• Your assigned tasks are complete

• You're done with this session and moving to other work

• User asks you to leave the session

DIFFERENCE from terminate_session: This is for individual agents leaving. Only the orchestrator should call terminate_session to end the entire session.

PARAMETERS:

• session_id: Session to leave

• agent_id: Your agent ID

• reason: Optional reason for leaving (helps other agents understand)

Terminate and complete a collaboration session. Orchestrator only.

AUTOMATIC TRIGGERS - Call this when:

• All tasks in the session are completed

• You want to formally end the collaboration

• Session goal has been achieved

Only the orchestrator should call this. All artifacts are preserved and can be exported to the main library.

WORKFLOW POSITION: Last tool in collaboration workflow (before export).

PARAMETERS:

• session_id: Session to terminate

• orchestrator_id: The orchestrator's agent ID

• summary: Optional final summary of the session's work

After termination, use export_to_library to persist findings.

Export session artifacts as findings in the main OpenLMLib library.

AUTOMATIC TRIGGERS - Call this when:

• A collaboration session is completed

• You want to persist session work to the main knowledge base

• Future sessions might need this knowledge

After a session completes, use this to permanently store the research outputs in the main library for future retrieval.

WORKFLOW POSITION: After session termination, before starting new work.

PARAMETERS:

• session_id: Completed session to export

• agent_id: Orchestrator agent ID authorizing the export

• project: Project name for findings (defaults to session title)

• confidence: Default confidence 0.0-1.0 (default: 0.8)

• tags: Additional tags to apply to all findings

• artifact_ids: Specific artifacts to export (None = all)

• include_summary: Also export the session summary as a finding (default: True)

List available session templates. Pre-built plans for common research patterns.

AUTOMATIC TRIGGERS - Call this when:

• Starting a new session and want a structured plan

• User asks to use a template

• Looking for recommended workflows (deep_research, code_review, etc.)

After finding a template, use create_from_template to start.

Get details of a specific session template. See the plan and rules before using.

AUTOMATIC TRIGGERS - Call this when:

• You want to review a template before creating a session

• Checking what tasks are in a template's plan

• User asks about a specific template

PARAMETERS:

• template_id: Template identifier (e.g., 'deep_research', 'code_review')

Create a session from a predefined template. Structured plan + rules in one step.

AUTOMATIC TRIGGERS - Call this when:

• User asks to start a session with a template

• You want a pre-built plan instead of creating tasks manually

• Starting common workflows (deep research, code review, etc.)

WORKFLOW POSITION: Alternative to create_session when you want a structured plan.

PARAMETERS:

• template_id: Template to use (e.g., 'deep_research', 'code_review')

• title: Session title

• task_description: Specific task description for this session

• created_by: Creator identifier (default: "orchestrator")

Get all sessions an agent has participated in. Track agent's work history.

AUTOMATIC TRIGGERS - Call this when:

• User asks "what sessions have I been in?"

• Looking for past work by a specific agent

• Finding related sessions to continue work

PARAMETERS:

• agent_id: Agent id and/or model name (matches ephemeral ids via agents.model)

• requesting_agent_id: Must be same agent id/model identity (own history only)

• status: Filter by session status - "active", "completed", "terminated" (optional)

Get a summary of all active sessions. Quick overview of ongoing work.

AUTOMATIC TRIGGERS - Call this when:

• User asks "what's happening?" or "what sessions are active?"

• Checking workload before joining a new session

• Getting a high-level view of all current collaboration work

PARAMETERS:

• agent_id: Your agent ID (summary is scoped to sessions you joined)

Search across all sessions by message content.

Uses FTS5 full-text search to find sessions matching the query.

Args: query: Search query (supports FTS5 syntax) status: Filter by session status (optional) limit: Max results (default 20)

Returns: Dict with matching sessions ranked by relevance

Find sessions related to a given session. Discover cross-session context.

AUTOMATIC TRIGGERS - Call this when:

• "What other sessions is this related to?"

• Looking for prior work by the same team

• Finding sessions that share agents or orchestrator

Identifies related sessions based on shared agents or same orchestrator.

PARAMETERS:

• session_id: Base session to find relationships for

• agent_id: Your agent ID (must belong to the session)

Get detailed statistics for a session. Messages, agents, artifacts, and timing.

AUTOMATIC TRIGGERS - Call this when:

• "How active was this session?"

• Measuring session productivity

• Comparing sessions by message volume

Includes message counts, breakdown by type and agent, artifact count, and time range.

PARAMETERS:

• session_id: Session to get statistics for

• agent_id: Your agent ID (must belong to the session)

Browse available models from OpenRouter API. Filter by provider, price, or context size.

AUTOMATIC TRIGGERS - Call this when:

• User asks what models are available

• Choosing a model for a collab session

• Comparing model pricing or context limits

Requires OPENROUTER_API_KEY environment variable. Results cached for 1 hour.

PARAMETERS:

• search: Search term in model name or description (optional)

• provider: Filter by provider like 'openai', 'anthropic', 'google' (optional)

• max_price_per_million: Max combined input+output price per 1M tokens (optional)

• context_length_min: Minimum context length in tokens (optional)

• is_free: Only include free models (default: False)

• force_refresh: Force fresh API call, ignoring cache (default: False)

Get detailed information about a specific OpenRouter model. Pricing, context, description.

AUTOMATIC TRIGGERS - Call this when:

• You have a model ID and need full details

• Checking pricing or context limits for a specific model

• Evaluating if a model is suitable for a task

Use list_models first to find model IDs.

PARAMETERS:

• model_id: Full model ID (e.g., 'anthropic/claude-sonnet-4')

Get recommended OpenRouter models for a specific task type. Pre-filtered best choices.

AUTOMATIC TRIGGERS - Call this when:

• "What model should I use for X?"

• Choosing models for a session without browsing the full catalog

• User asks for model recommendations

Task types: research, coding, analysis, writing, summarization, orchestrator, worker.

PARAMETERS:

• task_type: What the model will be used for

Get the Phase 0 Co-Scientist scope and safety policy.

AUTOMATIC TRIGGERS - Call this when:

• Planning a Co-Scientist or hypothesis-generation workflow

• Checking what topics are allowed before creating research sessions

• Reviewing human approval gates for multi-agent research

WORKFLOW POSITION: Use before Co-Scientist session creation.

Returns accepted domains, blocked domains, approval-required actions, and Phase 0 limits.

Screen a proposed Co-Scientist run before creating sessions.

AUTOMATIC TRIGGERS - Call this when:

• User asks to start Co-Scientist, hypothesis generation, or hypothesis verification

• You need to decide whether a multi-agent research topic is in scope

• A request may require human approval before state-changing or high-stakes action

WORKFLOW POSITION: First gate before any Co-Scientist session creation.

PARAMETERS:

• topic: Proposed research objective

• constraints: Optional hard limits, domain notes, or requested actions

Returns allowed status, risk level, matched categories, reasons, and required approvals. If allowed=False, do not create a Co-Scientist session.

Get the Phase 1 Co-Scientist hypothesis packet schema.

AUTOMATIC TRIGGERS - Call this when:

• Creating hypotheses for a Co-Scientist generation session

• Preparing packets to send into an independent verification session

• A client needs the required fields, ID formats, score ranges, or status values

WORKFLOW POSITION: Use after scope screening and before saving or sending hypothesis packet artifacts.

Returns a JSON-compatible schema description for artifact-first hypothesis packets.

Get Phase 6 Co-Scientist evidence labels and quality rubric.

AUTOMATIC TRIGGERS - Call this when:

• Creating or checking Co-Scientist hypothesis evidence

• A verifier needs the accepted support/refute/neutral labels

• A client needs the deterministic evidence quality levels

WORKFLOW POSITION: Use before writing hypothesis evidence or verification reports that will be promoted to verification.

Verify Co-Scientist citations against URLs, artifacts, or local files.

AUTOMATIC TRIGGERS - Call this when:

• Preflighting hypothesis packet citations before verification handoff

• Checking verification report citations before submission

• A citation may refer to an artifact ID or local workspace file

WORKFLOW POSITION: Use after packet validation and before start_hypothesis_verification or submit_verification.

PARAMETERS:

• citations: Non-empty list of citation strings

• session_ids: Optional session IDs to scope artifact citation lookup

Validate a Co-Scientist hypothesis packet before verification.

AUTOMATIC TRIGGERS - Call this when:

• A generation agent proposes a hypothesis packet

• Before saving a hypothesis packet artifact

• Before sending a hypothesis to a verification session

• You need actionable errors for missing citations, evidence, lineage, or scores

WORKFLOW POSITION: Gate every packet before verification. If valid=False, fix the returned issues before continuing.

PARAMETERS:

• packet: JSON-compatible hypothesis packet object

Returns valid status, issue count, and actionable validation issues.

Create a linked Co-Scientist generation and verification workflow.

AUTOMATIC TRIGGERS - Call this when:

• User asks to start a Co-Scientist run

• You need two linked sessions for hypothesis generation and independent verification

• A research task should generate hypotheses and verify them without transcript leakage

WORKFLOW POSITION: Use after confirming the topic is in scope. This creates both the generation and verification sessions in one call.

PARAMETERS:

• topic: Research objective for the run

• constraints: Optional limits, domain notes, or requested actions

• created_by: Creator/model identifier

• top_k: Default number of hypotheses to send to verification

Submit a validated hypothesis packet to a Co-Scientist run.

AUTOMATIC TRIGGERS - Call this when:

• A generation session has produced a hypothesis packet

• You need to persist a packet before ranking or verification

• You want run state to index the packet without copying large JSON into chat

WORKFLOW POSITION: Use during the generation phase after validate_hypothesis_packet passes.

PARAMETERS:

• run_id: Co-Scientist run ID

• hypothesis_packet: JSON-compatible hypothesis packet

• created_by: Optional submitting agent ID or model identifier

List compact hypothesis summaries for a Co-Scientist run.

AUTOMATIC TRIGGERS - Call this when:

• Inspecting generated hypotheses

• Selecting hypotheses for verification

• Checking which packets have been sent to verification

PARAMETERS:

• run_id: Co-Scientist run ID

• status: Optional packet status filter

Send selected Co-Scientist hypotheses to the verification session.

AUTOMATIC TRIGGERS - Call this when:

• Generation has produced a shortlist

• You need to transfer top hypotheses to independent verification

• You want to avoid copying the full generation transcript

WORKFLOW POSITION: Use after submit_hypothesis has indexed at least one packet. If hypothesis_ids is omitted, top_k highest-scored packets are sent.

PARAMETERS:

• run_id: Co-Scientist run ID

• hypothesis_ids: Optional explicit hypothesis IDs to verify

• top_k: Optional override for how many top hypotheses to send

• created_by: Optional actor for the handoff artifact/message

Submit a verification report for one Co-Scientist hypothesis.

AUTOMATIC TRIGGERS - Call this when:

• A verification agent has adjudicated a hypothesis

• You need to persist verdict, confidence, evidence, tests, and citations

• You are completing the one-report-per-hypothesis handoff

PARAMETERS:

• run_id: Co-Scientist run ID

• hypothesis_id: Hypothesis being verified

• verification_report: JSON-compatible verification report

• created_by: Optional submitting agent ID or model identifier

Get the current synthesized state of a Co-Scientist run.

AUTOMATIC TRIGGERS - Call this when:

• Inspecting linked generation and verification progress

• Checking whether selected hypotheses have reports

• Preparing a final Co-Scientist summary

PARAMETERS:

• run_id: Co-Scientist run ID

Create the final Co-Scientist report artifact for a verified run.

AUTOMATIC TRIGGERS - Call this when:

• All selected hypotheses have verification reports

• The user asks for the final Co-Scientist report

• You need a durable report artifact before export or memory preservation

WORKFLOW POSITION: Use after submit_verification has completed for every selected hypothesis. This creates one co_scientist_report artifact and compact session summaries for future recall.

PARAMETERS:

• run_id: Co-Scientist run ID

• created_by: Optional report creator identifier

• mark_complete: If true, move run phase to complete

Export supported Co-Scientist claims into the main knowledge library.

AUTOMATIC TRIGGERS - Call this when:

• A final Co-Scientist report exists and supported claims should become findings

• You need to preserve verified claims but skip inconclusive or rejected ones

• The user explicitly asks to save verified Co-Scientist results to memory

WORKFLOW POSITION: Use after final report review. This intentionally skips inconclusive, contradicted, and unsafe/out-of-scope hypotheses.

PARAMETERS:

• run_id: Co-Scientist run ID

• created_by: Session orchestrator agent_id or model (required)

• project: Optional project name for exported findings

• tags: Optional extra tags

• proposed_by: Optional proposer identifier

Evaluate a completed or in-progress Co-Scientist run.

AUTOMATIC TRIGGERS - Call this when:

• Measuring whether a Co-Scientist run improved traceability

• Tracking citation coverage, contradiction discovery, or verified hypothesis cost

• Comparing the two-session workflow against simpler baselines

PARAMETERS:

• run_id: Co-Scientist run ID

• token_count: Optional total token count for the run

• cost_usd: Optional total model cost for the run

• human_edits_needed: Optional number of final report edits

• expert_accepted: Optional user/expert acceptance flag

Get the built-in Phase 9 Co-Scientist benchmark task set.

AUTOMATIC TRIGGERS - Call this when:

• Setting up a benchmark for single-agent vs multi-agent vs Co-Scientist runs

• You need fixed research tasks for repeatable workflow comparison

• Evaluating whether Co-Scientist should be the default for a task class

Compare benchmark results across workflow types.

AUTOMATIC TRIGGERS - Call this when:

• You have benchmark results for single_agent, one_session_multi_agent, or two_session_co_scientist

• Deciding whether the simpler workflow should remain the default

• Comparing quality and traceability across research workflows

PARAMETERS:

• results: List of workflow result dicts or pre-evaluated result dicts

Get help about all collab MCP tools or a specific tool.

Call this with no arguments to see all available tools and their purposes. Call with a specific tool_name to get detailed usage instructions.

Args: tool_name: Optional specific tool name to get help for (e.g., 'create_session')

Returns: Dict with tool descriptions and usage information