OpenLMlib
Allows ingesting session activity from git history to automatically build memory without manual logging.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OpenLMlib search for findings about contextual chunking"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OpenLMlib
Local knowledge and research library for LLM workflows
Store, retrieve, and collaborate on findings with semantic search, full-text search, and multi-agent collaboration sessions.
๐ Full Documentation ยท Quickstart ยท MCP Tools ยท CollabSessions
Features
Knowledge Base: SQLite metadata + JSON findings + FAISS/Numpy vector index
Semantic Retrieval: Multi-phase retrieval with semantic + lexical search, deduplication, and reranking
MCP Server: 76 tools for AI assistants (17 core + 11 memory + 48 collaboration)
CollabSessions: Multi-agent collaboration with message passing, artifacts, and templates
Co-Scientist Workflow: Linked hypothesis generation and independent verification sessions
CLI: Full command-line interface for management and diagnostics
Portable: Findings exportable as JSON, easy backup and restore
Related MCP server: vectorlane
Quickstart
Installation
npm install -g openlmlib
openlmlib setup # Interactive wizard with React TUIOther options:
pipx (Python only)
pipx install openlmlib
openlmlib setupFrom Source
git clone https://github.com/Vedant9500/LMlib.git
cd LMlib
pip install -e .
openlmlib setupNote: The embedding model (~100-500MB) downloads during
setup, not installation.
First Steps
# Check health
openlmlib doctor
# Add a finding
openlmlib add \
--project myproj \
--claim "Contextual chunking improves retrieval by 15-30%" \
--confidence 0.85 \
--evidence "https://arxiv.org/example" \
--reasoning "Benchmarks show context-aware chunking outperforms fixed-size"
# Search
openlmlib query "retrieval techniques" --final-k 5
# List findings
openlmlib list --limit 20Configure AI Assistants
# Interactive setup (recommended)
openlmlib setup
# Or configure specific IDEs
openlmlib mcp-config --ide vscode --ide cursor
# Codex CLI / Claude Code
openlmlib mcp-config --ide codex_cli --ide claude_codeEach MCP client needs its own config entry. A custom prompt in Antigravity can
encourage OpenLMlib usage there, but Codex or Claude will not see the MCP until
openlmlib is registered in their MCP config and the client is restarted or
refreshed.
MCP startup is optimized for a fast client handshake. The server registers tools first, then starts a delayed runtime/model prewarm in the background so the first semantic retrieval is usually warm by the time you need it. To tune or disable that behavior, set environment variables in the client's OpenLMlib server entry:
[mcp_servers.openlmlib.env]
OPENLMLIB_MCP_PREWARM = "1" # default: 1
OPENLMLIB_MCP_PREWARM_DELAY_SEC = "5" # default: 5
OPENLMLIB_EMBED_PREWARM = "1" # default: 1Set OPENLMLIB_MCP_PREWARM = "0" if you want no background model work. The
main-thread OPENLMLIB_MCP_PREIMPORT_EMBEDDINGS = "1" option is still available
for unusual environments, but it can add 10+ seconds to MCP startup on Windows.
Supported clients: VS Code, Cursor, Claude Desktop, Claude Code, Gemini CLI, Aider, Windsurf, Zed, Cline, and more.
For hypothesis-generation workflows, configure the client first, then ask for a Co-Scientist run or use wording such as "research this and verify the hypotheses". See MCP client integration and system prompt templates.
What Can You Do?
๐ Build a Knowledge Base
Store findings from research, experiments, or analysis with structured metadata:
openlmlib add \
--project retrieval \
--claim "Dynamic chunk sizing reduces hallucination by 20%" \
--confidence 0.78 \
--evidence "https://example.com/study" \
--reasoning "Adaptive chunk size based on query complexity..." \
--caveats "Requires query complexity estimation" \
--tags retrieval,chunking,evaluation๐ Retrieve with Context
Multi-phase retrieval combines semantic similarity, lexical matching, and recency:
# Semantic search with reasoning traces
openlmlib query "contextual retrieval" \
--final-k 5 \
--reasoning-trace
# With filters
openlmlib query "retrieval" \
--project myproj \
--tags retrieval \
--confidence-min 0.8๐ค Use with AI Assistants
76 MCP tools let AI assistants securely access and modify your knowledge base:
Core Tools (17):
init_library,health- Setup and diagnosticssave_finding,delete_finding- Write operations (require confirmation)retrieve_findings,search_findings,search_knowledge- Retrieval and searchlist_findings,get_finding- Browse findingsretrieve_context- Format findings for LLM promptsstart_research,end_session- Composite workflow toolscheck_context,save_finding_auto- Convenience toolsevaluate_retrieval,get_usage_analytics,help_library- Utilities
๐ See all 76 tools โ
๐ฅ Multi-Agent Collaboration
CollabSessions enable structured collaboration between multiple LLM agents:
# Create session from template
openlmlib-mcp --call create_from_template '{
"template_id": "deep_research",
"title": "Research on Retrieval",
"created_by": "gpt-4"
}'
# Join session
openlmlib-mcp --call join_session '{
"session_id": "sess_20260409_abc12345",
"model": "claude-3",
"role": "worker"
}'
# Send and receive messages
openlmlib-mcp --call send_message '{...}'
openlmlib-mcp --call poll_messages '{...}'
# Add artifacts (reports, analysis)
openlmlib-mcp --call save_artifact '{...}'Available Templates:
deep_research- Comprehensive research (5 steps, 5 agents)code_review- Multi-agent code review (5 steps, 4 agents)market_analysis- Market/competitor analysis (4 steps, 4 agents)incident_investigation- Root cause analysis (4 steps, 3 agents)literature_review- Academic literature review (6 steps, 5 agents)co_scientist_generate- Co-Scientist hypothesis generation (6 steps, 7 agents)co_scientist_verify- Co-Scientist independent verification (5 steps, 6 agents)
๐ Full CollabSessions guide โ
๐ง Memory System (Session Persistence & Retrieval)
OpenLMlib includes a powerful memory system that persists session knowledge across work sessions, enabling AI assistants to "remember" what happened in previous sessions and continue work seamlessly.
Key Features:
Session Lifecycle: Start/end sessions with automatic context injection and summarization
Progressive Retrieval: 3-layer disclosure (search index โ timeline โ full details) for token efficiency
Retroactive Ingestion: Auto-ingest session activity from git history โ no manual logging needed!
Caveman Compression: Ultra-compressed context injection (46% token savings)
Memory Tools (11 tools):
session_start - Start session with context from previous sessions
session_end - End session and auto-generate summary
log_observation - Log tool executions for memory building
query_memory - Adaptive memory retriever for relevant observations
search_memory - Layer 1: Search index (~75 tokens/result)
memory_timeline - Layer 2: Chronological context (~200 tokens/result)
get_observations - Layer 3: Full details (~750 tokens/result)
inject_context - Auto-inject relevant context at session start
session_recap - Synthesized recap of recent sessions (~150-250 tokens)
topic_context - Deep dive on specific topics (~500-800 tokens)
ingest_git_history - Auto-ingest from git history (no manual logging!)Example Workflow:
# Start of session - automatically loads relevant context
session_start(
session_id="sess_20260414_001",
query="memory retrieval optimization"
)
# Returns: Context from previous sessions with relevant observations
# During work - observations are logged automatically
log_observation(
session_id="sess_20260414_001",
tool_name="Edit",
tool_input="Modified memory_retriever.py",
tool_output="Added auto_inject_context method"
)
# End of session - auto-generates summary
session_end(session_id="sess_20260414_001")
# Creates synthesized knowledge: files touched, decisions, next steps
# Next session - continue seamlessly
session_recap(limit=3)
# Returns: Structured knowledge from last 3 sessionsToken Efficiency:
Layer 1 only: 75 tokens/result (search index for filtering)
Layer 1+2: 275 tokens/result (timeline context)
Layer 1+2+3: 1,025 tokens/result (full details only for relevant items)
vs. full dump: 3-13x token savings!
Architecture
OpenLMlib
โโโ Knowledge Base
โ โโโ SQLite (metadata, full-text search)
โ โโโ FAISS/Numpy (vector index)
โ โโโ JSON findings (portable, human-readable)
โ
โโโ MCP Server (76 tools)
โ โโโ 17 core library tools
โ โโโ 11 memory tools (session lifecycle, adaptive retrieval, retroactive ingestion)
โ โโโ 48 collaboration tools
โ
โโโ CLI
โ โโโ Setup and configuration
โ โโโ Finding management
โ โโโ Diagnostics (doctor command)
โ
โโโ CollabSessions
โโโ Message bus (SQLite + JSONL)
โโโ Artifact store
โโโ Session templates
โโโ Context compactionDocumentation
๐ Complete documentation is in the docs/ folder:
docs/README.md - Documentation index and quick reference
docs/MCP_TOOLS.md - Complete reference for all 76 MCP tools
docs/COLLAB_SESSIONS.md - Multi-agent collaboration guide
docs/SYSTEM_PROMPT.md - Agent instruction templates
CLI Reference
# Setup and diagnostics
openlmlib setup # First-run bootstrap
openlmlib doctor # Health check
openlmlib --version # Show version
# Knowledge base
openlmlib init # Initialize storage
openlmlib add # Add finding
openlmlib list # List findings
openlmlib get # Get finding details
openlmlib query # Semantic retrieval
openlmlib delete # Delete finding
# Collaboration
openlmlib-mcp # MCP server (auto-configured)
# Backup and restore
openlmlib backup # Create backup
openlmlib restore # Restore from backupConfiguration
Global Install
Settings:
~/.openlmlib/config/settings.jsonData:
~/.openlmlib/data/
Local/Dev Install
Pass
--settings /path/to/settings.json
Uninstallation
# Remove package
npm uninstall -g openlmlib # if installed via npm
pipx uninstall openlmlib # if installed via pipx
pip uninstall openlmlib # if installed from source
# Remove data (optional)
rm -rf ~/.openlmlib # global install data
rm -rf data/ # local install dataDevelopment
git clone https://github.com/Vedant9500/LMlib.git
cd LMlib
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev,faiss]"
# Run tests
python -m unittest discover -s tests -p "test_*.py" -v
# Run MCP server manually
python -m openlmlib.mcp_server --settings ./config/settings.jsonNotes
Vector Search: Uses FAISS if installed, otherwise Numpy fallback
Embedding Model:
BAAI/bge-small-en-v1.5(default; 384-d, best accuracy/speed balance)Python: Requires 3.10+
Global vs Local: Global installs use
~/.openlmlib/, local uses projectdata/
Releases
Versioning: Semantic versioning (MAJOR.MINOR.PATCH)
Changelog: CHANGELOG.md
Release process: RELEASE.md
Contributing
See CONTRIBUTING.md for development workflow and guidelines.
License
MIT License - see LICENSE
Available Tools
76 toolscheck_contextA
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: []}
Inputs: query (required), project.
compare_co_scientist_workflowsA
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
Inputs: results (required).
create_co_scientist_final_reportA
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
Inputs: run_id (required), created_by, mark_complete.
create_co_scientist_runA
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
Inputs: topic (required), top_k, created_by, constraints.
create_from_templateA
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")
Inputs: title (required), template_id (required), task_description (required), created_by.
create_sessionA
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.
Inputs: title (required), task_description (required), plan, rules, +1 more.
delete_findingA
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)
Inputs: finding_id (required), confirm.
end_sessionA
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.
Inputs: session_id (required), project, export_to_library.
evaluate_co_scientist_runA
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
Inputs: run_id (required), cost_usd, token_count, expert_accepted, +1 more.
evaluate_retrievalA
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)
Inputs: final_k, dataset_path.
export_co_scientist_findingsA
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
Inputs: run_id (required), created_by (required), tags, project, +1 more.
export_to_libraryA
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)
Inputs: session_id (required), tags, project, agent_id, +3 more.
get_agent_sessionsA
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)
Inputs: agent_id (required), requesting_agent_id (required), status.
get_artifactA
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)
Inputs: agent_id (required), session_id (required), artifact_id (required).
get_co_scientist_benchmark_tasksA
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
Inputs: no named parameters.
get_co_scientist_reportB
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
Inputs: run_id (required).
get_co_scientist_scope_policyA
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.
Inputs: no named parameters.
get_evidence_quality_rubricA
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.
Inputs: no named parameters.
get_findingA
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.
Inputs: finding_id (required).
get_hypothesis_packet_schemaA
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.
Inputs: no named parameters.
get_model_detailsA
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')
Inputs: model_id (required).
get_observationsA
[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
Inputs: ids (required).
get_session_stateA
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)
Inputs: agent_id (required), session_id (required).
get_templateA
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')
Inputs: template_id (required).
get_usage_analyticsA
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.
Inputs: days, tool_name.
grep_artifactsA
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)
Inputs: pattern (required), agent_id (required), session_id (required), created_by.
grep_messagesA
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)
Inputs: pattern (required), agent_id (required), session_id (required), limit, +1 more.
healthA
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.
Inputs: no named parameters.
help_collabA
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
Inputs: tool_name.
help_libraryA
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
Inputs: tool_name.
ingest_git_historyB
Auto-ingest session activity from git history. NO manual logging needed!
Inputs: session_id (required), time_window_hours, include_uncommitted.
init_libraryA
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.
Inputs: no named parameters.
inject_contextA
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
Inputs: session_id (required), limit, query, user_id.
join_sessionA
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.
Inputs: model (required), session_id (required), capabilities.
leave_sessionA
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)
Inputs: agent_id (required), session_id (required), reason.
list_artifactsA
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)
Inputs: agent_id (required), session_id (required), created_by, artifact_type.
list_findingsA
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)
Inputs: limit, offset.
list_hypothesesA
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
Inputs: run_id (required), status.
list_modelsA
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)
Inputs: search, is_free, provider, force_refresh, +2 more.
list_sessionsA
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)
Inputs: limit, status.
list_templatesA
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.
Inputs: no named parameters.
log_observationA
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.
Inputs: tool_name (required), session_id (required), tool_input (required), tool_output (required).
memory_timelineA
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")
Inputs: ids (required), window.
poll_messagesA
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)
Inputs: agent_id (required), session_id (required), limit, timeout, +2 more.
query_memoryA
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": "..."}
Inputs: query (required), limit, filters.
read_message_rangeA
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)
Inputs: end_seq (required), agent_id (required), start_seq (required), session_id (required).
read_messagesA
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)
Inputs: agent_id (required), session_id (required), limit, msg_types, +1 more.
recommended_modelsA
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
Inputs: task_type (required).
retrieve_contextA
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)
Inputs: query (required), tags, final_k, project, +1 more.
retrieve_findingsA
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.
Inputs: query (required), tags, final_k, project, +5 more.
save_artifactA
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)
Inputs: title (required), content (required), created_by (required), session_id (required), +3 more.
save_findingA
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.
Inputs: claim (required), project (required), tags, caveats, +7 more.
save_finding_autoA
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)
Inputs: claim (required), project (required), tags, caveats, +4 more.
screen_co_scientist_scopeA
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.
Inputs: topic (required), constraints.
search_findingsA
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)
Inputs: query (required), limit.
search_knowledgeA
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.
Inputs: query (required), limit.
search_memoryA
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": "..."}
Inputs: query (required), limit, filters.
search_sessionsB
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
Inputs: query (required), agent_id (required), limit, status.
send_messageA
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
Inputs: content (required), msg_type (required), session_id (required), metadata, +2 more.
session_contextB
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)
Inputs: agent_id (required), session_id (required), max_messages.
session_endA
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)
Inputs: session_id (required).
session_recapA
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)
Inputs: limit, session_id.
session_relationshipsA
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)
Inputs: agent_id (required), session_id (required).
sessions_summaryA
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)
Inputs: agent_id (required).
session_startA
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).
Inputs: session_id (required), limit, query, user_id.
session_statisticsA
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)
Inputs: agent_id (required), session_id (required).
start_hypothesis_verificationA
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
Inputs: run_id (required), top_k, created_by, hypothesis_ids.
start_researchA
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.
Inputs: topic (required), session_id (required), limit, user_id.
submit_hypothesisA
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
Inputs: run_id (required), hypothesis_packet (required), created_by.
submit_verificationA
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
Inputs: run_id (required), hypothesis_id (required), verification_report (required), created_by.
tail_messagesA
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)
Inputs: agent_id (required), session_id (required), n.
terminate_sessionA
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.
Inputs: session_id (required), orchestrator_id (required), summary.
topic_contextA
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)
Inputs: topic (required), session_id.
update_session_stateA
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)
Inputs: state (required), session_id (required), orchestrator_id (required).
validate_hypothesis_packetA
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.
Inputs: packet (required).
verify_co_scientist_citationsA
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
Inputs: citations (required), session_ids.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 76 tools
Multiple tools have nearly identical purposes: search_knowledge, search_findings, retrieve_findings, retrieve_context, search_memory, and query_memory all retrieve knowledge with only subtle differences. Session and message reading also overlap heavily (session_context vs get_session_state, read_messages vs poll_messages vs tail_messages), so agents will frequently select the wrong tool.
Subsets are internally consistent (save_finding/list_findings, create_session/join_session/leave_session), but the overall set mixes styles: session_start vs start_research, session_end vs end_session, search_findings vs search_knowledge, and help_library vs help_collab. Several tools are single nouns or noun phrases, and get_observations is explicitly deprecated but still exposed.
76 tools is far beyond a well-scoped MCP server; even 25+ is considered heavy. The set spans findings, session memory, collaboration, OpenRouter model lookup, templates, analytics, and Co-Scientist workflows, so most tools are tangential to any single task.
Despite the large surface, there are obvious lifecycle gaps: delete_finding says to 'update instead' but no update_finding tool exists, and save_finding encourages updating duplicates without providing an update path. Artifacts and templates similarly lack update/delete operations, leaving agent workflows with dead ends.
Maintenance
Related MCP Connectors
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Shared long-term memory vault for AI agents with 20 MCP tools.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides AI agents with persistent knowledge storage, enabling them to store, search, and retrieve text, documents, and files using semantic and keyword search via MCP tools.34Apache 2.0
- AlicenseNot gradedqualityCmaintenanceProvides a local vector memory store for AI agents with semantic search, offline embeddings, and MCP integration, enabling tools like Claude and Cursor to store and retrieve information without cloud dependencies.4 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage, upload, chunk, and semantically search local documents through MCP tools and a REST API, with a built-in web dashboard and optional Gemini-powered AI search.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to store, retrieve, and manage persistent memories locally via an MCP server with hybrid vector and keyword search, plus tools for memory CRUD, search, backup, and import.MIT