{ "schemaVersion": "1.0", "item": { "slug": "telnyx-rag", "name": "Telnyx Rag", "source": "tencent", "type": "skill", "category": "效率提升", "sourceUrl": "https://clawhub.ai/teamtelnyx/telnyx-rag", "canonicalUrl": "https://clawhub.ai/teamtelnyx/telnyx-rag", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/telnyx-rag", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=telnyx-rag", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "ask.py", "config.json", "diagram.svg", "embed.sh", "search.py" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/telnyx-rag" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/telnyx-rag", "agentPageUrl": "https://openagent3.xyz/skills/telnyx-rag/agent", "manifestUrl": "https://openagent3.xyz/skills/telnyx-rag/agent.json", "briefUrl": "https://openagent3.xyz/skills/telnyx-rag/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Telnyx RAG Memory", "body": "Semantic search and RAG-powered Q&A over your OpenClaw workspace using Telnyx's native embedding, similarity search, and inference APIs." }, { "title": "Requirements", "body": "Your own Telnyx API Key — each user/agent uses their own key\nPython 3.8+ — stdlib only, no external dependencies\nGet your API key at portal.telnyx.com" }, { "title": "Bucket Naming Convention", "body": "Use a consistent naming scheme so anyone can adopt this:\n\nopenclaw-{agent-id}\n\nAgentBucketChief (main)openclaw-mainBob the Builderopenclaw-builderVoice agentopenclaw-voiceYour agentopenclaw-{your-id}\n\nWhy?\n\nPredictable: anyone can find any agent's bucket\nCollision-free: scoped to agent, not person or team\nDiscoverable: openclaw-* prefix groups all agent buckets in Telnyx Storage UI" }, { "title": "Quick Start", "body": "cd ~/skills/telnyx-rag\n\n# Set YOUR Telnyx API key (each user/agent uses their own)\necho 'TELNYX_API_KEY=KEY...' > .env\n\n# Run setup with validation\n./setup.sh --check # Validate requirements first\n./setup.sh # Full setup (uses bucket from config.json)\n\n# Search your memory\n./search.py \"What are my preferences?\"\n\n# Ask questions (full RAG pipeline)\n./ask.py \"What is the porting process?\"" }, { "title": "What It Does", "body": "Indexes your workspace files (MEMORY.md, memory/*.md, knowledge/, skills/)\nChunks large files intelligently (markdown by headers, JSON/Slack by threads)\nEmbeds content automatically using Telnyx AI\nSearches using natural language queries with retry logic\nAnswers questions using a full RAG pipeline (retrieve → rerank → generate)\nPrioritizes results from memory/ (your primary context)\nIncremental sync — only uploads changed files\nOrphan cleanup — removes deleted files from bucket" }, { "title": "Option 1: Environment Variable", "body": "export TELNYX_API_KEY=\"KEY...\"\n./setup.sh" }, { "title": "Option 2: .env File", "body": "echo 'TELNYX_API_KEY=KEY...' > .env\n./setup.sh" }, { "title": "Validation Mode", "body": "./setup.sh --check # Validate requirements without making changes" }, { "title": "Custom Bucket Name", "body": "./setup.sh my-custom-bucket" }, { "title": "Ask Questions (RAG Pipeline)", "body": "# Basic question answering\n./ask.py \"What is Telnyx's porting process?\"\n\n# Show retrieved context alongside answer\n./ask.py \"How do I deploy?\" --context\n\n# Use a different model\n./ask.py \"Explain voice setup\" --model meta-llama/Meta-Llama-3.1-8B-Instruct\n\n# More/fewer context chunks\n./ask.py \"meeting decisions\" --num 12\n\n# JSON output for scripting\n./ask.py \"API usage limits\" --json\n\n# Search a different bucket\n./ask.py \"project timeline\" --bucket work-memory" }, { "title": "Search Memory", "body": "# Basic search with improved error handling\n./search.py \"What are David's communication preferences?\"\n\n# Search specific bucket\n./search.py \"meeting notes\" --bucket my-other-bucket\n\n# More results with timeout control\n./search.py \"procedures\" --num 10 --timeout 45\n\n# JSON output (for scripts)\n./search.py \"procedures\" --json" }, { "title": "Sync Files (with Chunking)", "body": "# Incremental sync with auto-chunking\n./sync.py\n\n# Override chunk size (tokens)\n./sync.py --chunk-size 600\n\n# Quiet mode for cron jobs\n./sync.py --quiet\n\n# Remove orphaned files (including stale chunks)\n./sync.py --prune\n\n# Sync + trigger embedding\n./sync.py --embed\n\n# Check status\n./sync.py --status\n\n# List indexed files (shows chunks too)\n./sync.py --list" }, { "title": "Watch Mode", "body": "# Watch for changes and auto-sync with chunking\n./sync.py --watch" }, { "title": "Trigger Embedding", "body": "# Trigger embedding for current bucket\n./embed.sh\n# OR\n./sync.py --embed\n\n# Check embedding status\n./sync.py --embed-status \n\nWhy is this needed? Uploading files to Telnyx Storage doesn't automatically generate embeddings. The embedding process converts your files into searchable vectors. Without this step, search.py and ask.py won't return results." }, { "title": "Configuration", "body": "Edit config.json to customize behavior:\n\n{\n \"bucket\": \"openclaw-memory\",\n \"region\": \"us-central-1\",\n \"workspace\": \".\",\n \"patterns\": [\n \"MEMORY.md\",\n \"memory/*.md\",\n \"knowledge/*.json\",\n \"skills/*/SKILL.md\"\n ],\n \"priority_prefixes\": [\"memory/\", \"MEMORY.md\"],\n \"default_num_docs\": 5,\n \"chunk_size\": 800,\n \"ask_model\": \"meta-llama/Meta-Llama-3.1-70B-Instruct\",\n \"ask_num_docs\": 8,\n \"retrieve_num_docs\": 20\n}" }, { "title": "Config Fields", "body": "FieldDefaultDescriptionbucketopenclaw-{agent-id}Telnyx Storage bucket name (see naming convention)regionus-central-1Storage regionworkspace.Root directory to scan for filespatterns(see above)Glob patterns for files to indexpriority_prefixes[\"memory/\", \"MEMORY.md\"]Sources to rank higher in resultsexclude[\"*.tmp\", ...]Patterns to excludechunk_size800Target tokens per chunk (~4 chars/token)ask_modelMeta-Llama-3.1-70B-InstructLLM model for ask.pyask_num_docs8Final context chunks for LLMretrieve_num_docs20Initial retrieval count (before reranking)" }, { "title": "How It Works", "body": "┌─────────────────┐ ┌──────────────────────────────────┐\n│ Your Workspace │ │ Telnyx Cloud │\n│ ├── memory/ │ │ │\n│ ├── knowledge/ │──┐ │ Storage: your-bucket/ │\n│ └── skills/ │ │ │ └── file__chunk-001.md │\n└─────────────────┘ │ │ └── file__chunk-002.md │\n │ │ │ │\n Smart Chunking ◀──┘ │ ▼ embed │\n ├── Markdown: split │ Telnyx AI Embeddings │\n │ on ## headers │ │ │\n ├── JSON/Slack: split │ ▼ │\n │ by thread/time │ Similarity Search │\n └── Metadata tags │ │ │\n └──────────────┼──────────────────┘\n │\n ask.py Pipeline: │\n ┌─────────────────────────────────┐ │\n │ 1. Retrieve top-20 chunks ◀────┘ │\n │ 2. Rerank (TF-IDF + priority) │\n │ 3. Deduplicate adjacent chunks │\n │ 4. Build prompt with top-8 │\n │ 5. Call Telnyx Inference LLM │\n │ 6. Return answer + sources │\n └─────────────────────────────────┘" }, { "title": "Smart Chunking", "body": "Large files are automatically split into semantic chunks before upload:" }, { "title": "Markdown Files", "body": "Split on ## and ### headers first\nIf a section is still too large, split by paragraph boundaries\nEach chunk gets a metadata header with source, chunk index, and title" }, { "title": "JSON / Slack Exports", "body": "Messages grouped by token budget per chunk\nExtracts: channel name, date range, authors\nMetadata includes Slack-specific fields" }, { "title": "Chunk Naming", "body": "Chunks use deterministic filenames:\n\nknowledge/meetings.md → knowledge/meetings__chunk-001.md\n knowledge/meetings__chunk-002.md\n knowledge/meetings__chunk-003.md" }, { "title": "Chunk Metadata", "body": "Each chunk includes a YAML-style header:\n\n---\nsource: knowledge/meetings.md\nchunk: 2/5\ntitle: Q4 Planning Discussion\n---\n\n(chunk content here)\n\nFor Slack exports, additional fields:\n\n---\nsource: slack/general.json\nchunk: 3/12\ntitle: general\nchannel: general\ndate_range: 2024-01-15 to 2024-01-16\nauthors: alice, bob, charlie\n---" }, { "title": "Chunk Lifecycle", "body": "When a source file changes, old chunks are deleted and new ones uploaded\nChunk mappings tracked in .sync-state.json\n--prune cleans up orphaned chunks from deleted files" }, { "title": "Reranking (ask.py)", "body": "The RAG pipeline uses a multi-signal reranking strategy:\n\nSemantic similarity — Telnyx embedding distance (certainty score)\nKeyword overlap — TF-IDF weighted term matching with the query\nPriority boost — Chunks from priority_prefixes sources ranked higher\nDeduplication — Adjacent chunks from the same source with >80% token overlap are merged\n\nInitial retrieval fetches retrieve_num_docs (default 20), reranking selects the best ask_num_docs (default 8) for the LLM prompt." }, { "title": "Smart Chunking", "body": "Semantic splitting: Headers for markdown, threads for Slack JSON\nMetadata headers: Source, chunk index, title in every chunk\nConfigurable size: --chunk-size flag or chunk_size in config\nDeterministic names: Reproducible chunk filenames" }, { "title": "RAG Q&A Pipeline (ask.py)", "body": "End-to-end: Query → retrieve → rerank → generate → answer\nTelnyx Inference: Uses Telnyx LLM API for generation\nSource references: Every answer includes source file citations\nContext mode: --context shows retrieved chunks\nJSON output: --json for structured responses" }, { "title": "Reranking", "body": "Multi-signal scoring: Combines embedding similarity + keyword overlap + priority\nDeduplication: Removes near-identical adjacent chunks\nConfigurable: Retrieve 20, use best 8 (tunable)" }, { "title": "Incremental Sync (v1)", "body": "File hashing: Tracks SHA-256 hashes in .sync-state.json\nSkip unchanged: Only uploads modified files\nProgress tracking: Shows progress bars for large syncs" }, { "title": "Smart Cleanup", "body": "--prune: Removes files from bucket that were deleted locally\nChunk-aware: Cleans up orphaned chunks too\nState tracking: Maintains sync history and chunk mappings" }, { "title": "Improved Reliability", "body": "Retry logic: 3 attempts with exponential backoff\nBetter errors: Parses Telnyx API error responses\nTimeout control: Configurable request timeouts\nQuiet mode: --quiet flag for cron jobs" }, { "title": "OpenClaw Integration", "body": "Add to your TOOLS.md:\n\n## Semantic Memory & Q&A\n\nAsk questions about your workspace:\n\\`\\`\\`bash\ncd ~/skills/telnyx-rag && ./ask.py \"your question\"\n\\`\\`\\`\n\nSearch memory semantically:\n\\`\\`\\`bash\ncd ~/skills/telnyx-rag && ./search.py \"your query\"\n\\`\\`\\`" }, { "title": "Automated Sync", "body": "Add to your heartbeat or cron:\n\n# Quiet sync with orphan cleanup\ncd ~/skills/telnyx-rag && ./sync.py --quiet --prune\n\n# Sync with embedding\ncd ~/skills/telnyx-rag && ./sync.py --quiet --embed" }, { "title": "Setup Issues", "body": "\"Python version too old\"\n\nRequires Python 3.8+\nCheck: python3 --version\n\n\"API key test failed\"\n\nVerify key: echo $TELNYX_API_KEY\nGet new key at portal.telnyx.com" }, { "title": "Sync Issues", "body": "\"Bucket not found\"\n\n./sync.py --create-bucket\n\n\"No results found\"\n\nWait 1-2 minutes after sync (embeddings take time)\nCheck files uploaded: ./sync.py --list\nTrigger embedding: ./sync.py --embed\n\n\"Files not syncing\"\n\nCheck .sync-state.json for corruption\nForce re-sync: rm .sync-state.json && ./sync.py" }, { "title": "Ask Issues", "body": "\"LLM generation failed\"\n\nCheck API key has inference permissions\nTry a different model: ./ask.py \"query\" --model meta-llama/Meta-Llama-3.1-8B-Instruct\n\n\"No relevant documents found\"\n\nEnsure files are synced and embedded\nTry broader query terms" }, { "title": "From Python", "body": "from ask import ask\nfrom search import search_memory\n\n# Ask a question (full RAG pipeline)\nanswer = ask(\"What is the deployment process?\")\nprint(answer)\n\n# With options\nanswer = ask(\n \"project timeline\",\n num_final=5,\n model=\"meta-llama/Meta-Llama-3.1-8B-Instruct\",\n show_context=True,\n output_json=True,\n)\nprint(answer)\n\n# Basic search\nresults = search_memory(\"What do I know about X?\", num_docs=5)\nprint(results)" }, { "title": "From Bash", "body": "# Ask and capture answer\nanswer=$(./ask.py \"What are the API limits?\" --json)\n\n# Search and capture JSON\nresults=$(./search.py \"query\" --json)" }, { "title": "Performance Tips", "body": "Tune chunk_size — Smaller chunks (400-600) for precise retrieval, larger (800-1200) for more context\nUse --quiet for cron jobs to reduce output\nEnable --prune periodically to clean up deleted files\nWatch mode is great for development: ./sync.py --watch\nBatch embedding by syncing first, then embedding: ./sync.py && ./sync.py --embed" }, { "title": "Credits", "body": "Built for OpenClaw using Telnyx Storage and AI APIs." } ], "body": "Telnyx RAG Memory\n\nSemantic search and RAG-powered Q&A over your OpenClaw workspace using Telnyx's native embedding, similarity search, and inference APIs.\n\nRequirements\nYour own Telnyx API Key — each user/agent uses their own key\nPython 3.8+ — stdlib only, no external dependencies\nGet your API key at portal.telnyx.com\nBucket Naming Convention\n\nUse a consistent naming scheme so anyone can adopt this:\n\nopenclaw-{agent-id}\n\nAgent\tBucket\nChief (main)\topenclaw-main\nBob the Builder\topenclaw-builder\nVoice agent\topenclaw-voice\nYour agent\topenclaw-{your-id}\n\nWhy?\n\nPredictable: anyone can find any agent's bucket\nCollision-free: scoped to agent, not person or team\nDiscoverable: openclaw-* prefix groups all agent buckets in Telnyx Storage UI\nQuick Start\ncd ~/skills/telnyx-rag\n\n# Set YOUR Telnyx API key (each user/agent uses their own)\necho 'TELNYX_API_KEY=KEY...' > .env\n\n# Run setup with validation\n./setup.sh --check # Validate requirements first\n./setup.sh # Full setup (uses bucket from config.json)\n\n# Search your memory\n./search.py \"What are my preferences?\"\n\n# Ask questions (full RAG pipeline)\n./ask.py \"What is the porting process?\"\n\nWhat It Does\nIndexes your workspace files (MEMORY.md, memory/*.md, knowledge/, skills/)\nChunks large files intelligently (markdown by headers, JSON/Slack by threads)\nEmbeds content automatically using Telnyx AI\nSearches using natural language queries with retry logic\nAnswers questions using a full RAG pipeline (retrieve → rerank → generate)\nPrioritizes results from memory/ (your primary context)\nIncremental sync — only uploads changed files\nOrphan cleanup — removes deleted files from bucket\nSetup Options\nOption 1: Environment Variable\nexport TELNYX_API_KEY=\"KEY...\"\n./setup.sh\n\nOption 2: .env File\necho 'TELNYX_API_KEY=KEY...' > .env\n./setup.sh\n\nValidation Mode\n./setup.sh --check # Validate requirements without making changes\n\nCustom Bucket Name\n./setup.sh my-custom-bucket\n\nUsage\nAsk Questions (RAG Pipeline)\n# Basic question answering\n./ask.py \"What is Telnyx's porting process?\"\n\n# Show retrieved context alongside answer\n./ask.py \"How do I deploy?\" --context\n\n# Use a different model\n./ask.py \"Explain voice setup\" --model meta-llama/Meta-Llama-3.1-8B-Instruct\n\n# More/fewer context chunks\n./ask.py \"meeting decisions\" --num 12\n\n# JSON output for scripting\n./ask.py \"API usage limits\" --json\n\n# Search a different bucket\n./ask.py \"project timeline\" --bucket work-memory\n\nSearch Memory\n# Basic search with improved error handling\n./search.py \"What are David's communication preferences?\"\n\n# Search specific bucket\n./search.py \"meeting notes\" --bucket my-other-bucket\n\n# More results with timeout control\n./search.py \"procedures\" --num 10 --timeout 45\n\n# JSON output (for scripts)\n./search.py \"procedures\" --json\n\nSync Files (with Chunking)\n# Incremental sync with auto-chunking\n./sync.py\n\n# Override chunk size (tokens)\n./sync.py --chunk-size 600\n\n# Quiet mode for cron jobs\n./sync.py --quiet\n\n# Remove orphaned files (including stale chunks)\n./sync.py --prune\n\n# Sync + trigger embedding\n./sync.py --embed\n\n# Check status\n./sync.py --status\n\n# List indexed files (shows chunks too)\n./sync.py --list\n\nWatch Mode\n# Watch for changes and auto-sync with chunking\n./sync.py --watch\n\nTrigger Embedding\n# Trigger embedding for current bucket\n./embed.sh\n# OR\n./sync.py --embed\n\n# Check embedding status\n./sync.py --embed-status \n\n\nWhy is this needed? Uploading files to Telnyx Storage doesn't automatically generate embeddings. The embedding process converts your files into searchable vectors. Without this step, search.py and ask.py won't return results.\n\nConfiguration\n\nEdit config.json to customize behavior:\n\n{\n \"bucket\": \"openclaw-memory\",\n \"region\": \"us-central-1\",\n \"workspace\": \".\",\n \"patterns\": [\n \"MEMORY.md\",\n \"memory/*.md\",\n \"knowledge/*.json\",\n \"skills/*/SKILL.md\"\n ],\n \"priority_prefixes\": [\"memory/\", \"MEMORY.md\"],\n \"default_num_docs\": 5,\n \"chunk_size\": 800,\n \"ask_model\": \"meta-llama/Meta-Llama-3.1-70B-Instruct\",\n \"ask_num_docs\": 8,\n \"retrieve_num_docs\": 20\n}\n\nConfig Fields\nField\tDefault\tDescription\nbucket\topenclaw-{agent-id}\tTelnyx Storage bucket name (see naming convention)\nregion\tus-central-1\tStorage region\nworkspace\t.\tRoot directory to scan for files\npatterns\t(see above)\tGlob patterns for files to index\npriority_prefixes\t[\"memory/\", \"MEMORY.md\"]\tSources to rank higher in results\nexclude\t[\"*.tmp\", ...]\tPatterns to exclude\nchunk_size\t800\tTarget tokens per chunk (~4 chars/token)\nask_model\tMeta-Llama-3.1-70B-Instruct\tLLM model for ask.py\nask_num_docs\t8\tFinal context chunks for LLM\nretrieve_num_docs\t20\tInitial retrieval count (before reranking)\nHow It Works\n┌─────────────────┐ ┌──────────────────────────────────┐\n│ Your Workspace │ │ Telnyx Cloud │\n│ ├── memory/ │ │ │\n│ ├── knowledge/ │──┐ │ Storage: your-bucket/ │\n│ └── skills/ │ │ │ └── file__chunk-001.md │\n└─────────────────┘ │ │ └── file__chunk-002.md │\n │ │ │ │\n Smart Chunking ◀──┘ │ ▼ embed │\n ├── Markdown: split │ Telnyx AI Embeddings │\n │ on ## headers │ │ │\n ├── JSON/Slack: split │ ▼ │\n │ by thread/time │ Similarity Search │\n └── Metadata tags │ │ │\n └──────────────┼──────────────────┘\n │\n ask.py Pipeline: │\n ┌─────────────────────────────────┐ │\n │ 1. Retrieve top-20 chunks ◀────┘ │\n │ 2. Rerank (TF-IDF + priority) │\n │ 3. Deduplicate adjacent chunks │\n │ 4. Build prompt with top-8 │\n │ 5. Call Telnyx Inference LLM │\n │ 6. Return answer + sources │\n └─────────────────────────────────┘\n\nSmart Chunking\n\nLarge files are automatically split into semantic chunks before upload:\n\nMarkdown Files\nSplit on ## and ### headers first\nIf a section is still too large, split by paragraph boundaries\nEach chunk gets a metadata header with source, chunk index, and title\nJSON / Slack Exports\nMessages grouped by token budget per chunk\nExtracts: channel name, date range, authors\nMetadata includes Slack-specific fields\nChunk Naming\n\nChunks use deterministic filenames:\n\nknowledge/meetings.md → knowledge/meetings__chunk-001.md\n knowledge/meetings__chunk-002.md\n knowledge/meetings__chunk-003.md\n\nChunk Metadata\n\nEach chunk includes a YAML-style header:\n\n---\nsource: knowledge/meetings.md\nchunk: 2/5\ntitle: Q4 Planning Discussion\n---\n\n(chunk content here)\n\n\nFor Slack exports, additional fields:\n\n---\nsource: slack/general.json\nchunk: 3/12\ntitle: general\nchannel: general\ndate_range: 2024-01-15 to 2024-01-16\nauthors: alice, bob, charlie\n---\n\nChunk Lifecycle\nWhen a source file changes, old chunks are deleted and new ones uploaded\nChunk mappings tracked in .sync-state.json\n--prune cleans up orphaned chunks from deleted files\nReranking (ask.py)\n\nThe RAG pipeline uses a multi-signal reranking strategy:\n\nSemantic similarity — Telnyx embedding distance (certainty score)\nKeyword overlap — TF-IDF weighted term matching with the query\nPriority boost — Chunks from priority_prefixes sources ranked higher\nDeduplication — Adjacent chunks from the same source with >80% token overlap are merged\n\nInitial retrieval fetches retrieve_num_docs (default 20), reranking selects the best ask_num_docs (default 8) for the LLM prompt.\n\nNew Features (v2)\nSmart Chunking\nSemantic splitting: Headers for markdown, threads for Slack JSON\nMetadata headers: Source, chunk index, title in every chunk\nConfigurable size: --chunk-size flag or chunk_size in config\nDeterministic names: Reproducible chunk filenames\nRAG Q&A Pipeline (ask.py)\nEnd-to-end: Query → retrieve → rerank → generate → answer\nTelnyx Inference: Uses Telnyx LLM API for generation\nSource references: Every answer includes source file citations\nContext mode: --context shows retrieved chunks\nJSON output: --json for structured responses\nReranking\nMulti-signal scoring: Combines embedding similarity + keyword overlap + priority\nDeduplication: Removes near-identical adjacent chunks\nConfigurable: Retrieve 20, use best 8 (tunable)\nIncremental Sync (v1)\nFile hashing: Tracks SHA-256 hashes in .sync-state.json\nSkip unchanged: Only uploads modified files\nProgress tracking: Shows progress bars for large syncs\nSmart Cleanup\n--prune: Removes files from bucket that were deleted locally\nChunk-aware: Cleans up orphaned chunks too\nState tracking: Maintains sync history and chunk mappings\nImproved Reliability\nRetry logic: 3 attempts with exponential backoff\nBetter errors: Parses Telnyx API error responses\nTimeout control: Configurable request timeouts\nQuiet mode: --quiet flag for cron jobs\nOpenClaw Integration\n\nAdd to your TOOLS.md:\n\n## Semantic Memory & Q&A\n\nAsk questions about your workspace:\n\\`\\`\\`bash\ncd ~/skills/telnyx-rag && ./ask.py \"your question\"\n\\`\\`\\`\n\nSearch memory semantically:\n\\`\\`\\`bash\ncd ~/skills/telnyx-rag && ./search.py \"your query\"\n\\`\\`\\`\n\nAutomated Sync\n\nAdd to your heartbeat or cron:\n\n# Quiet sync with orphan cleanup\ncd ~/skills/telnyx-rag && ./sync.py --quiet --prune\n\n# Sync with embedding\ncd ~/skills/telnyx-rag && ./sync.py --quiet --embed\n\nTroubleshooting\nSetup Issues\n\n\"Python version too old\"\n\nRequires Python 3.8+\nCheck: python3 --version\n\n\"API key test failed\"\n\nVerify key: echo $TELNYX_API_KEY\nGet new key at portal.telnyx.com\nSync Issues\n\n\"Bucket not found\"\n\n./sync.py --create-bucket\n\n\n\"No results found\"\n\nWait 1-2 minutes after sync (embeddings take time)\nCheck files uploaded: ./sync.py --list\nTrigger embedding: ./sync.py --embed\n\n\"Files not syncing\"\n\nCheck .sync-state.json for corruption\nForce re-sync: rm .sync-state.json && ./sync.py\nAsk Issues\n\n\"LLM generation failed\"\n\nCheck API key has inference permissions\nTry a different model: ./ask.py \"query\" --model meta-llama/Meta-Llama-3.1-8B-Instruct\n\n\"No relevant documents found\"\n\nEnsure files are synced and embedded\nTry broader query terms\nAPI Reference\nFrom Python\nfrom ask import ask\nfrom search import search_memory\n\n# Ask a question (full RAG pipeline)\nanswer = ask(\"What is the deployment process?\")\nprint(answer)\n\n# With options\nanswer = ask(\n \"project timeline\",\n num_final=5,\n model=\"meta-llama/Meta-Llama-3.1-8B-Instruct\",\n show_context=True,\n output_json=True,\n)\nprint(answer)\n\n# Basic search\nresults = search_memory(\"What do I know about X?\", num_docs=5)\nprint(results)\n\nFrom Bash\n# Ask and capture answer\nanswer=$(./ask.py \"What are the API limits?\" --json)\n\n# Search and capture JSON\nresults=$(./search.py \"query\" --json)\n\nPerformance Tips\nTune chunk_size — Smaller chunks (400-600) for precise retrieval, larger (800-1200) for more context\nUse --quiet for cron jobs to reduce output\nEnable --prune periodically to clean up deleted files\nWatch mode is great for development: ./sync.py --watch\nBatch embedding by syncing first, then embedding: ./sync.py && ./sync.py --embed\nCredits\n\nBuilt for OpenClaw using Telnyx Storage and AI APIs." }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/teamtelnyx/telnyx-rag", "publisherUrl": "https://clawhub.ai/teamtelnyx/telnyx-rag", "owner": "teamtelnyx", "version": "1.0.1", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/telnyx-rag", "downloadUrl": "https://openagent3.xyz/downloads/telnyx-rag", "agentUrl": "https://openagent3.xyz/skills/telnyx-rag/agent", "manifestUrl": "https://openagent3.xyz/skills/telnyx-rag/agent.json", "briefUrl": "https://openagent3.xyz/skills/telnyx-rag/agent.md" } }