@wentorai/research-plugins 1.0.0 → 1.2.0

package/skills/tools/knowledge-graph/concept-map-generator/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: concept-map-generator
+description: "Generate structured concept maps from academic texts automatically"
+metadata:
+  openclaw:
+    emoji: "brain"
+    category: "tools"
+    subcategory: "knowledge-graph"
+    keywords: ["concept map", "knowledge representation", "text mining", "ontology", "semantic extraction", "mind map"]
+    source: "wentor-research-plugins"
+---
+
+# Concept Map Generator
+
+A skill for automatically generating structured concept maps from academic texts, lecture notes, and research papers. Covers concept extraction using NLP techniques, relationship identification, hierarchical organization, and export to visual formats. Concept maps differ from mind maps in that they explicitly label relationships between concepts, making them more suitable for representing scientific knowledge.
+
+## Concept Map Fundamentals
+
+### Structure of a Concept Map
+
+A concept map consists of three elements: concepts (nodes), linking phrases (labeled edges), and propositions (concept-link-concept triples that form meaningful statements).
+
+```
+Concept Map Elements:
+
+Concept: A perceived regularity or pattern designated by a label.
+  Examples: "DNA replication", "enzyme", "natural selection"
+  Representation: boxes or ovals containing short noun phrases
+
+Linking Phrase: Words that connect two concepts to form a proposition.
+  Examples: "is catalyzed by", "requires", "leads to", "is a type of"
+  Representation: labeled arrows between concept nodes
+
+Proposition: A meaningful statement formed by two concepts and a link.
+  Example: [DNA replication] --requires--> [DNA polymerase]
+  This reads: "DNA replication requires DNA polymerase"
+
+Cross-links: Connections between concepts in different domains or
+  branches of the map, showing integrative understanding.
+```
+
+### Concept Maps vs Mind Maps
+
+```
+Feature            Concept Map           Mind Map
+--------------     ------------------    ------------------
+Structure          Network (graph)       Tree (hierarchical)
+Relationships      Labeled explicitly    Implied by proximity
+Root node          May have multiple     Single central topic
+Cross-links        Encouraged            Rare
+Best for           Deep understanding    Brainstorming
+Scientific use     Knowledge modeling    Idea generation
+Reading direction  Follow arrow labels   Center outward
+```
+
+## Automated Concept Extraction
+
+### NLP Pipeline for Extraction
+
+```python
+import spacy
+
+def extract_concepts(text, nlp_model="en_core_web_sm"):
+    """
+    Extract candidate concepts from academic text using NLP.
+
+    Strategy:
+    1. Extract noun phrases as concept candidates
+    2. Filter by frequency and specificity
+    3. Merge overlapping spans
+    4. Rank by TF-IDF relevance
+    """
+    nlp = spacy.load(nlp_model)
+    doc = nlp(text)
+
+    # Extract noun phrases
+    candidates = []
+    for chunk in doc.noun_chunks:
+        # Remove determiners and leading adjectives for cleaner concepts
+        clean = chunk.text.strip()
+        if len(clean.split()) <= 4:  # Keep manageable length
+            candidates.append(clean.lower())
+
+    # Count frequencies
+    from collections import Counter
+    freq = Counter(candidates)
+
+    # Filter: keep concepts mentioned at least twice
+    concepts = [c for c, count in freq.most_common() if count >= 2]
+
+    return concepts
+```
+
+### Relationship Extraction
+
+```python
+def extract_relationships(text, concepts, nlp_model="en_core_web_sm"):
+    """
+    Extract relationships between concepts using dependency parsing.
+
+    Identifies verb phrases connecting known concepts in the same sentence.
+    """
+    nlp = spacy.load(nlp_model)
+    doc = nlp(text)
+    concept_set = set(concepts)
+
+    triples = []
+    for sent in doc.sents:
+        sent_text = sent.text.lower()
+        # Find which concepts appear in this sentence
+        found = [c for c in concept_set if c in sent_text]
+
+        if len(found) >= 2:
+            # Extract the verb connecting them
+            verbs = [token.lemma_ for token in sent
+                     if token.pos_ == "VERB"]
+            if verbs:
+                for i in range(len(found)):
+                    for j in range(i + 1, len(found)):
+                        triples.append({
+                            "source": found[i],
+                            "target": found[j],
+                            "relation": verbs[0],
+                            "sentence": sent.text
+                        })
+
+    return triples
+```
+
+## Hierarchical Organization
+
+### Building Concept Hierarchies
+
+Academic concept maps benefit from hierarchical organization, placing the most general, inclusive concepts at the top and progressively more specific concepts below.
+
+```
+Hierarchy Construction Algorithm:
+
+1. Identify superordinate concepts:
+   - Concepts that appear in titles, abstracts, section headings
+   - Concepts with the most outgoing relationships
+   - Concepts that subsume other concepts (hypernyms)
+
+2. Identify subordinate concepts:
+   - Concepts that are instances or types of superordinates
+   - Concepts with high specificity (long noun phrases)
+   - Concepts that appear only in methods/results sections
+
+3. Assign levels:
+   Level 0: Domain (e.g., "machine learning")
+   Level 1: Subdomains (e.g., "supervised learning", "unsupervised learning")
+   Level 2: Methods (e.g., "random forests", "k-means clustering")
+   Level 3: Details (e.g., "Gini impurity", "elbow method")
+
+4. Add cross-links between branches:
+   e.g., "random forests" --uses--> "bootstrap sampling"
+         (links supervised learning to statistical methods)
+```
+
+### Strategies for Academic Papers
+
+```
+Input: Research paper
+Output: Concept map organized by paper structure
+
+Section-Based Extraction:
+  Introduction -> Key concepts, research questions, theoretical framework
+  Methods -> Methodological concepts, tools, techniques, variables
+  Results -> Findings, measurements, statistical outcomes
+  Discussion -> Interpretations, implications, limitations
+
+Connection Types in Academic Maps:
+  "is defined as" - definitional relationships
+  "is measured by" - operationalization
+  "causes / leads to" - causal relationships
+  "is correlated with" - associative relationships
+  "is a type of" - taxonomic relationships
+  "is part of" - mereological relationships
+  "contradicts" - conflicting findings
+  "extends" - building on prior work
+```
+
+## Export and Visualization
+
+### Output Formats
+
+```python
+def export_to_graphml(concepts, relationships, output_path):
+    """
+    Export concept map to GraphML format for Gephi, yEd, or Cytoscape.
+    """
+    import networkx as nx
+
+    G = nx.DiGraph()
+
+    for concept in concepts:
+        G.add_node(concept, label=concept)
+
+    for rel in relationships:
+        G.add_edge(
+            rel["source"],
+            rel["target"],
+            label=rel["relation"]
+        )
+
+    nx.write_graphml(G, output_path)
+    return output_path
+
+
+def export_to_cmap(concepts, relationships, output_path):
+    """
+    Export to CXL format for CmapTools (IHMC).
+    CmapTools is the standard concept mapping software in education.
+    """
+    # CXL is an XML format specific to CmapTools
+    header = '<?xml version="1.0" encoding="UTF-8"?>\n'
+    header += '<cmap xmlns="http://cmap.ihmc.us/xml/cmap/">\n'
+
+    body = '  <map>\n'
+    for i, concept in enumerate(concepts):
+        body += f'    <concept id="c{i}" label="{concept}"/>\n'
+
+    for j, rel in enumerate(relationships):
+        src_id = concepts.index(rel["source"])
+        tgt_id = concepts.index(rel["target"])
+        body += (
+            f'    <connection id="conn{j}" '
+            f'from-id="c{src_id}" to-id="c{tgt_id}" '
+            f'label="{rel["relation"]}"/>\n'
+        )
+
+    body += '  </map>\n'
+    footer = '</cmap>\n'
+
+    with open(output_path, "w") as f:
+        f.write(header + body + footer)
+
+    return output_path
+```
+
+### Recommended Tools
+
+```
+CmapTools (IHMC):
+  - Free desktop application specifically designed for concept maps
+  - Collaborative editing, cloud hosting
+  - Export: CXL, image, PDF, web page
+  - Best for: Educational concept maps, collaborative projects
+
+yEd Graph Editor:
+  - Free desktop application with auto-layout algorithms
+  - Import: GraphML, Excel, CSV
+  - Hierarchical, organic, circular layouts
+  - Best for: Large concept maps needing automatic layout
+
+Mermaid.js (text-based):
+  - Embed concept maps in Markdown documents
+  - Version-controllable (plain text)
+  - Best for: Documentation, README files, lab notebooks
+```
+
+## Quality Criteria for Academic Concept Maps
+
+```
+Evaluation Rubric:
+
+Comprehensiveness: Does the map capture the key concepts?
+  - All major concepts from the source text should appear
+  - No important relationships should be missing
+
+Accuracy: Are the propositions correct?
+  - Each concept-link-concept triple should be factually accurate
+  - Linking phrases should precisely describe the relationship
+
+Hierarchy: Is the map well-organized?
+  - Most general concepts at top, specific at bottom
+  - Logical grouping of related concepts
+
+Cross-links: Does the map show integrative understanding?
+  - Links between different branches demonstrate deep understanding
+  - Cross-links are the most valuable part of a concept map
+```
+
+Concept maps serve as both learning tools and knowledge artifacts. In research, they help teams align on shared understanding of complex domains, identify knowledge gaps, and communicate theoretical frameworks to collaborators and reviewers.

package/skills/tools/knowledge-graph/graphiti-guide/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: graphiti-guide
+description: "Build real-time knowledge graphs for AI agents using Graphiti by Zep"
+metadata:
+  openclaw:
+    emoji: "🕸"
+    category: "tools"
+    subcategory: "knowledge-graph"
+    keywords: ["knowledge-graph", "ai-agents", "temporal-graphs", "neo4j", "memory", "entity-extraction"]
+    source: "https://github.com/getzep/graphiti"
+---
+
+# Graphiti Guide
+
+## Overview
+
+Graphiti is an open-source framework for building and querying dynamic, temporally-aware knowledge graphs designed specifically for AI agent applications. Developed by Zep, Graphiti enables agents to maintain persistent, structured memory that evolves over time, capturing entities, relationships, and facts extracted from conversational and documentary sources.
+
+Traditional knowledge graphs are static structures that require manual curation and batch updates. Graphiti takes a fundamentally different approach: it incrementally builds and updates the graph in real-time as new information arrives, resolving contradictions, merging duplicate entities, and maintaining temporal metadata that tracks when facts were established and whether they remain current.
+
+For academic researchers, Graphiti offers a powerful framework for constructing domain-specific knowledge graphs from research literature, experimental observations, and collaborative discussions. With over 23,000 GitHub stars, the project has gained significant traction in both the AI engineering and research communities as a practical bridge between unstructured text and structured, queryable knowledge.
+
+## Installation and Setup
+
+Install Graphiti via pip:
+
+```bash
+pip install graphiti-core
+```
+
+Graphiti requires a Neo4j database for graph storage. Set up Neo4j using Docker:
+
+```bash
+docker run -d \
+  --name neo4j-graphiti \
+  -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/your-password \
+  -e NEO4J_PLUGINS='["apoc"]' \
+  neo4j:5
+```
+
+Configure environment variables for your LLM provider and Neo4j connection:
+
+```bash
+export NEO4J_URI=bolt://localhost:7687
+export NEO4J_USER=neo4j
+export NEO4J_PASSWORD=$NEO4J_PASSWORD
+export OPENAI_API_KEY=$OPENAI_API_KEY
+```
+
+Initialize Graphiti in your Python project:
+
+```python
+from graphiti_core import Graphiti
+
+graphiti = Graphiti(
+    neo4j_uri="bolt://localhost:7687",
+    neo4j_user="neo4j",
+    neo4j_password=$NEO4J_PASSWORD,
+)
+
+# Build indices for efficient querying
+await graphiti.build_indices()
+```
+
+## Core Features
+
+**Incremental Graph Construction**: Add episodes of information that are automatically parsed into entities and relationships:
+
+```python
+from graphiti_core.nodes import EpisodeType
+from datetime import datetime
+
+# Add a research observation
+await graphiti.add_episode(
+    name="experiment_log_2026_03_10",
+    episode_body="""
+    The CRISPR-Cas9 experiment targeting gene BRCA1 in HeLa cells
+    showed 87% knockout efficiency. The guide RNA sequence gRNA-42
+    was designed using the Benchling platform. Dr. Chen supervised
+    the experiment, which used the protocol established in our
+    2025 Nature Methods paper.
+    """,
+    source=EpisodeType.text,
+    source_description="Lab notebook entry",
+    reference_time=datetime(2026, 3, 10),
+)
+```
+
+Graphiti automatically extracts entities (BRCA1, HeLa cells, Dr. Chen, gRNA-42, Benchling), establishes relationships (gRNA-42 targets BRCA1, Dr. Chen supervised the experiment), and records temporal metadata.
+
+**Temporal Awareness**: Knowledge graphs built with Graphiti track when facts were established and can reason about changes over time:
+
+```python
+# Add an update that modifies a previous fact
+await graphiti.add_episode(
+    name="experiment_update",
+    episode_body="""
+    After reanalysis, the CRISPR knockout efficiency for BRCA1
+    in HeLa cells was revised to 82% due to off-target effects
+    detected in the secondary sequencing run.
+    """,
+    source=EpisodeType.text,
+    source_description="Updated analysis",
+    reference_time=datetime(2026, 3, 12),
+)
+```
+
+The graph updates the efficiency value while maintaining the historical record, enabling queries about both current and historical states of knowledge.
+
+**Semantic Search**: Query the knowledge graph using natural language:
+
+```python
+# Search for relevant entities and facts
+results = await graphiti.search(
+    query="What is the knockout efficiency for BRCA1?",
+    num_results=5,
+)
+
+for result in results:
+    print(f"Fact: {result.fact}")
+    print(f"Source: {result.source_description}")
+    print(f"Valid from: {result.valid_at}")
+    print(f"Confidence: {result.score}")
+    print("---")
+```
+
+**Entity Resolution**: Graphiti handles duplicate and variant entity references automatically. References to "CRISPR-Cas9", "CRISPR", and "Cas9 system" are resolved to the appropriate entities based on context, reducing manual curation overhead.
+
+## Research Workflow Integration
+
+**Literature Knowledge Base**: Build a continuously growing knowledge graph from your reading notes and paper summaries:
+
+```python
+# Process a batch of paper summaries
+papers = [
+    {
+        "title": "Attention Is All You Need",
+        "summary": "Vaswani et al. introduced the Transformer architecture...",
+        "date": datetime(2017, 6, 12),
+    },
+    {
+        "title": "BERT: Pre-training of Deep Bidirectional Transformers",
+        "summary": "Devlin et al. proposed BERT, a masked language model...",
+        "date": datetime(2018, 10, 11),
+    },
+]
+
+for paper in papers:
+    await graphiti.add_episode(
+        name=paper["title"],
+        episode_body=paper["summary"],
+        source=EpisodeType.text,
+        source_description=f"Paper summary: {paper['title']}",
+        reference_time=paper["date"],
+    )
+```
+
+Then query across your entire reading history to find connections, trace the evolution of ideas, and identify foundational works.
+
+**Experimental Knowledge Management**: Track the relationships between experiments, reagents, instruments, protocols, and personnel. This creates an institutional memory that survives personnel turnover and helps new lab members quickly understand the research context.
+
+**Systematic Review Support**: As you read and annotate papers for a systematic review, feed summaries into Graphiti to build a structured representation of findings, methodologies, and populations studied. Query the resulting graph to identify patterns and gaps.
+
+**Agent Memory for Research Assistants**: Integrate Graphiti as the memory backend for AI research assistants. The agent can accumulate knowledge from each interaction and provide increasingly informed responses:
+
+```python
+# Research agent with persistent memory
+async def research_agent_step(user_query, conversation_context):
+    # Retrieve relevant knowledge
+    memories = await graphiti.search(
+        query=user_query,
+        num_results=10,
+    )
+
+    # Include memories in the agent context
+    context = format_memories(memories) + conversation_context
+
+    # Generate response using LLM
+    response = await generate_response(user_query, context)
+
+    # Store new knowledge from the interaction
+    await graphiti.add_episode(
+        name=f"conversation_{datetime.now().isoformat()}",
+        episode_body=f"User asked: {user_query}\nResponse: {response}",
+        source=EpisodeType.message,
+        source_description="Research assistant conversation",
+        reference_time=datetime.now(),
+    )
+
+    return response
+```
+
+## Graph Exploration and Maintenance
+
+Access the Neo4j browser at `http://localhost:7474` to visually explore your knowledge graph. Use Cypher queries for advanced exploration:
+
+```cypher
+// Find all entities related to a specific gene
+MATCH (e:Entity)-[r]-(connected)
+WHERE e.name CONTAINS 'BRCA1'
+RETURN e, r, connected
+LIMIT 50
+
+// Find the most connected entities (research hubs)
+MATCH (e:Entity)-[r]-()
+RETURN e.name, COUNT(r) AS connections
+ORDER BY connections DESC
+LIMIT 20
+```
+
+Periodically review and clean the graph to maintain quality. Remove incorrectly extracted entities and merge duplicates that automated resolution missed.
+
+## References
+
+- Graphiti repository: https://github.com/getzep/graphiti
+- Zep documentation: https://docs.getzep.com/
+- Neo4j graph database: https://neo4j.com/
+- Temporal knowledge graph concepts in the project documentation

package/skills/tools/knowledge-graph/mimir-memory-guide/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: mimir-memory-guide
+description: "Semantic vector search memory bank for AI agents"
+metadata:
+  openclaw:
+    emoji: "📝"
+    category: "tools"
+    subcategory: "knowledge-graph"
+    keywords: ["agent memory", "vector search", "semantic memory", "MCP", "knowledge persistence", "embedding"]
+    source: "https://github.com/orneryd/Mimir"
+---
+
+# Mimir Agent Memory Guide
+
+## Overview
+
+Mimir is a semantic memory bank for AI agents that provides persistent, searchable memory via vector embeddings. Agents can store observations, learnings, and context that persists across sessions, and retrieve relevant memories using semantic search. Available as an MCP server for seamless integration with Claude Code, OpenClaw, and other agent frameworks.
+
+## Installation
+
+```bash
+# MCP server
+npm install -g @mimir/mcp-server
+
+# Python library
+pip install mimir-memory
+```
+
+## MCP Configuration
+
+```json
+{
+  "mcpServers": {
+    "mimir": {
+      "command": "npx",
+      "args": ["@mimir/mcp-server"],
+      "env": {
+        "MEMORY_PATH": "~/.mimir/memories",
+        "EMBEDDING_MODEL": "all-MiniLM-L6-v2"
+      }
+    }
+  }
+}
+```
+
+## Core Operations
+
+```python
+from mimir import MemoryBank
+
+bank = MemoryBank(
+    path="./agent_memory",
+    embedding_model="all-MiniLM-L6-v2",
+)
+
+# Store a memory
+bank.store(
+    content="The project uses FastAPI with PostgreSQL. "
+            "Database migrations are managed with Alembic.",
+    metadata={
+        "type": "project_context",
+        "project": "wentor",
+        "timestamp": "2025-03-10",
+    },
+)
+
+# Semantic search
+results = bank.search(
+    query="How does the database work?",
+    top_k=5,
+)
+for r in results:
+    print(f"[{r.score:.3f}] {r.content[:100]}...")
+
+# Delete memory
+bank.delete(memory_id=results[0].id)
+```
+
+## MCP Tools
+
+```markdown
+### Available MCP Tools
+- `store_memory(content, metadata)` — Store new memory
+- `search_memory(query, limit)` — Semantic search
+- `list_memories(filter)` — List by metadata filter
+- `delete_memory(id)` — Remove specific memory
+- `clear_memories(filter)` — Clear matching memories
+
+### Usage in Agent Chat
+"Remember that the API uses JWT tokens with 30-day expiry"
+→ Stores as persistent memory
+
+"What do you know about the authentication system?"
+→ Searches memories, returns relevant stored context
+```
+
+## Memory Types
+
+```python
+# Structured memory categories
+bank.store(
+    content="User prefers dark theme and minimal logging",
+    metadata={"type": "preference"},
+)
+
+bank.store(
+    content="Fixed bug: ECharts CSS vars don't work on Canvas",
+    metadata={"type": "lesson_learned", "topic": "echarts"},
+)
+
+bank.store(
+    content="Deploy script is at deploy/deploy.sh, "
+            "requires .credentials file",
+    metadata={"type": "project_knowledge"},
+)
+
+# Search by type
+prefs = bank.search(
+    query="user preferences",
+    filter={"type": "preference"},
+)
+```
+
+## Use Cases
+
+1. **Agent memory**: Persistent context across sessions
+2. **Project knowledge**: Store and retrieve project facts
+3. **Learning accumulation**: Build expertise over time
+4. **Preference tracking**: Remember user preferences
+5. **Research notes**: Searchable research observations
+
+## References
+
+- [Mimir GitHub](https://github.com/orneryd/Mimir)
+- [MCP Specification](https://modelcontextprotocol.io/)