Ogm

OpenGraphMemory (OGM) Skill

This skill provides a comprehensive, unambiguous, production-grade operational guide for AI Agents interacting with OpenGraphMemory (OGM). It covers four core capabilities:

1. Hybrid RAG & Semantic Retrieval (Dense Vector pgvector + Knowledge Graph traversal via RRF).
2. Codebase AST Call-Graphs & Centrality (Tree-sitter continuous AST extraction).
3. Document Knowledge Graphs & Evidence Citations (LiteParse verbatim text & spatial bounding boxes).
4. Persistent Failure-Driven Agent Operational Memory (Bayesian confidence, closed-loop feedback, supersession).

⚡ Agent Lifecycle Trigger Matrix

Follow this 4-phase protocol during all pair-programming and engineering sessions:

🎯 Task Intent Routing (English & Indonesian Triggers)

🔍 Category 1: Hybrid RAG & Semantic Retrieval

English Triggers:

• "How does the authentication / payment / storage service work?"
• "Query documentation and code using Hybrid RAG"
• "Find relevant evidence and quotes for architecture spec X"

Indonesian Triggers:

• "Bagaimana cara kerja modul autentikasi / pembayaran / storage?"
• "Cari dokumentasi dan kode pakai hybrid RAG"
• "Temukan kutipan dan bukti teknis untuk spesifikasi X"

Action Protocol:

1. Call ogm_retrieval_query with dataset_id, query, and mode="hybrid" (combines vector and graph via RRF).
2. Inspect returned chunks and verbatim evidence citations.

💻 Category 2: Codebase AST Call-Graphs & Centrality

English Triggers:

• "Extract/index this codebase into OpenGraphMemory / OGM"
• "Build AST call-graph for project Y"
• "Which symbols are most connected / have top degree in repo Z?"
• "Who calls function process_payment?"

Indonesian Triggers:

• "Tolong extract codebase ini ke dalam knowledge graph menggunakan ogm"
• "Index repo ini ke dalam OGM"
• "Simbol apa yang paling banyak keterhubungannya / urutkan degree terbanyak"
• "Siapa saja yang memanggil fungsi process_payment?"

Action Protocol:

1. Full Repo Onboarding (Oneshot): Call ogm_index_codebase with dataset_id and path.
2. Incremental Single-File Edit: Call ogm_sync_code_file when editing 1 file during pair programming.
3. Symbol Search & Call Graphs: Use ogm_search_code_symbols and ogm_get_code_call_graph.
4. Degree Centrality Ranking: Use ogm_get_code_chunks to fetch hub nodes sorted by degree.

📄 Category 3: Document Upload & Knowledge Extraction

English Triggers:

• "Upload/index document spec.pdf or design.md into OGM"
• "Extract knowledge graph from document X"
• "Show evidence quotes for relation Y"

Indonesian Triggers:

• "Upload/index dokumen spec.pdf ke OGM"
• "Extract knowledge graph dari dokumen design.md"
• "Tampilkan bukti kutipan relasi Y"

Action Protocol:

1. Identify dataset (ogm_list_datasets).
2. Upload document using ogm_upload_document.
3. Inspect relation evidence quotes using ogm_get_evidence or ogm_get_relation_evidence.

🧠 Category 4: Persistent Agent Operational Memory Workflow

English Triggers:

• "Fix bug X", "Resolve error Y", "Failed test in Z"
• "Record verified fix for this issue"
• "Did we encounter this problem before?"

Indonesian Triggers:

• "Perbaiki error X", "Fix bug Y", "Test gagal di Z"
• "Catat solusi perbaikan ini ke memori"
• "Apakah masalah ini pernah terjadi sebelumnya?"

Action Protocol:

1. Recall: Call ogm_recall_code_memory or ogm_memory_search before making edits.
2. Reorient: Search again only when initial hypothesis is disproven.
3. Persist: Call ogm_record_code_fix or ogm_memory_record_outcome after test/build passes.

🔄 Category 5: Failure-Driven Hybrid RAG Tuning Protocol

English Triggers:

• "Tune RAG retrieval for query X using failure memory"
• "Compare vector vs graph retrieval for Y"
• "Why did RAG retrieve the wrong context for Z?"
• "Ablate retrieval weights vector_weight vs graph_weight"

Indonesian Triggers:

• "Tuning RAG query X pakai memory kegagalan"
• "Bandingkan hasil vector dan graph retrieval untuk Y"
• "Kenapa retrieval RAG salah mengambil konteks untuk Z?"
• "Kalibrasi bobot vector_weight dan graph_weight untuk query ini"

Action Protocol:

1. Pre-flight Failure Recall: Call ogm_memory_search(q="retrieval failure <topic>", problem_signature="rag_retrieval_<dataset>") or ogm_recall_code_memory before difficult queries to check if past attempts failed due to vector hallucination or graph sparsity.
2. Ablation & Comparison: Call ogm_retrieval_query with compare=True. Examine parallel scores for vector, graph, and hybrid.
   • If multi-hop relations/callers are missing: increase graph_weight (0.7..0.9) or set mode="graph".
   • If terminology is paraphrased or entities are sparse: increase vector_weight (0.7..0.9) or set mode="vector".
3. Failure Logging: If retrieval fails to return the required context leading to an incorrect agent response, log the failed attempt via ogm_memory_append_attempt(episode_id, hypothesis="vector_weight=0.5 failed to find callers", result="failed") or downvote via ogm_memory_feedback_episode(score=-1).
4. Persistence & Pattern Promotion: Once the optimal weights/mode successfully retrieve the correct evidence, record the verified outcome via ogm_memory_record_outcome or ogm_record_code_fix with the tuned vector_weight, graph_weight, and mode in the lesson field. This promotes the pattern via Bayesian confidence scoring so future agent sessions inherit the tuned parameters.

🛠️ Complete 22-Tool MCP Cheat Sheet & Zero-Loop Rules

Zero-Loop Policy & Direct Tool Execution

• NEVER run curl commands to /v1/... API endpoints manually.
• NEVER inspect OpenAPI schemas (openapi.json) or run custom regex/Node.js fallback scripts.
• ALWAYS call the matching ogm_* MCP tool directly in 1 single tool call (oneshot).

🛠️ MCP Tool Workflows & Examples

1. Hybrid RAG Query Workflow

{
  "dataset_id": "core-backend",
  "query": "How does token validation and session expiration work?",
  "mode": "hybrid",
  "top_k": 10
}

Tool: ogm_retrieval_query

2. Recall Memory Before Bug Fix

{
  "file_path": "apps/api/app/routers/retrieval.py",
  "q": "deadlock during bulk insert"
}

Tool: ogm_recall_code_memory / ogm_memory_search

3. Record Verified Fix After Passing Tests

{
  "file_path": "apps/api/app/routers/retrieval.py",
  "title": "Fix database deadlock during batch insert",
  "goal": "Prevent concurrent transaction lock collisions",
  "root_cause": "Unordered bulk insert resulted in cross-table row lock deadlocks",
  "solution": "Sort batch rows by primary key before bulk insert and acquire advisory lock"
}

Tool: ogm_record_code_fix

4. Codebase Oneshot Indexing

{
  "dataset_id": "ds_my_project",
  "path": "/workspace/my-project"
}

Tool: ogm_index_codebase

5. Live Incremental Code File Sync

{
  "dataset_id": "ds_my_project",
  "file_path": "src/auth/jwt.py",
  "code": "def verify_token(token: str) -> bool:\n    ...",
  "language": "python"
}

Tool: ogm_sync_code_file