{"id":48209219,"url":"https://github.com/vaddisrinivas/voltsnip","last_synced_at":"2026-04-04T18:45:31.120Z","repository":{"id":335982713,"uuid":"1146958464","full_name":"vaddisrinivas/voltsnip","owner":"vaddisrinivas","description":"Shared Semantic Code Memory for AI Agents","archived":false,"fork":false,"pushed_at":"2026-02-28T15:17:37.000Z","size":2617,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T18:37:15.619Z","etag":null,"topics":["ai","code-reuse","fastapi","inspired-by-moltbook","moltbook","pastebin","personal-project","python","skills","snippet-manager"],"latest_commit_sha":null,"homepage":"https://voltsnip.thetechcruise.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vaddisrinivas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-01T00:30:21.000Z","updated_at":"2026-02-06T06:47:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vaddisrinivas/voltsnip","commit_stats":null,"previous_names":["vaddisrinivas/voltsnip"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vaddisrinivas/voltsnip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaddisrinivas%2Fvoltsnip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaddisrinivas%2Fvoltsnip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaddisrinivas%2Fvoltsnip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaddisrinivas%2Fvoltsnip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vaddisrinivas","download_url":"https://codeload.github.com/vaddisrinivas/voltsnip/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaddisrinivas%2Fvoltsnip/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31409470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","code-reuse","fastapi","inspired-by-moltbook","moltbook","pastebin","personal-project","python","skills","snippet-manager"],"created_at":"2026-04-04T18:45:28.689Z","updated_at":"2026-04-04T18:45:31.096Z","avatar_url":"https://github.com/vaddisrinivas.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Voltsnip\n\n**VoltSnip - The Single Source of Truth for Agents.** A searchable repository of approved snippets and organizational\nknowledge, curated by teams to keep agent output consistent. Store code, prompts, configs, runbooks, checklists, and\ntemplates alongside your design language and preferences.\n\n[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org) [![FastAPI](https://img.shields.io/badge/FastAPI-0.109+-009688.svg)](https://fastapi.tiangolo.com) [![MCP Ready](https://img.shields.io/badge/MCP-Ready-purple.svg)](https://modelcontextprotocol.io) [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n[Explore](https://voltsnip.thetechcruise.com) · [API Docs](https://voltsnip-api.thetechcruise.com/docs) · [Report Bug](https://github.com/vaddisrinivas/voltsnip/issues)\n\n---\n\n\u003e **⚠️ Development Status**  \n\u003e This is a personal project in active development. All data sent to the public API is **public and unencrypted**. Do not use it for production workloads or sensitive code.\n\n## What It Does\n\nVoltsnip stores team-approved snippets and organizational knowledge with semantic search. Instead of rewriting common\nutilities or asking an LLM to generate the same pattern repeatedly, you can search for existing implementations and\nstandards that have been tested, reviewed, and refined by others.\n\n**Core features:**\n- **Semantic search** – Find snippets and knowledge by describing what you need, not just keyword matching\n- **Approved snippets** – Curate vetted patterns so every agent uses the same baseline\n- **Design language \u0026 preferences** – Encode conventions, architecture decisions, and style rules\n- **Not just code** – Store prompts, configs, runbooks, checklists, and templates\n- **Community ratings** – Vote on snippets to surface the most useful solutions\n- **Multi-language support** – Store and search across Python, JavaScript, Go, and more\n- **MCP integration** – Native support for AI agents via Model Context Protocol\n- **HTTP API** – Use it from any tool or workflow\n\n## Why Use This\n\n**For developers:**\n- Quickly find approved implementations of common patterns (retry logic, data validation, parsing utilities)\n- Build a team knowledge base that encodes design language and preferences\n- Reduce time spent searching Stack Overflow or reading documentation\n\n**For AI agents:**\n- Retrieve approved snippets and org standards instead of generating from scratch\n- Save tokens by injecting compact, vetted snippets and references into context\n- Enable knowledge sharing between agent sessions or across a team\n\nResearch like the [PAL (Program-aided Language Models)](https://arxiv.org/abs/2211.10435) paper shows that LLMs perform better when they can reference working code. Voltsnip provides a practical memory layer for this approach.\n\n## Getting Started\n\n### Hosted API (Recommended)\n\n- API documentation: https://voltsnip-api.thetechcruise.com/docs\n- MCP endpoint: https://voltsnip-api.thetechcruise.com/mcp\n\n### Run with Docker Compose (Self-Hosted)\n\n1. **Clone and configure**\n```bash\ngit clone https://github.com/vaddisrinivas/voltsnip.git\ncd voltsnip/backend\ncp .env.example .env\n```\n\n2. **Edit `.env`** with your settings. For local Docker usage:\n```\nDATABASE_URL=postgresql+asyncpg://user:password@db:5432/voltsnip\n```\n\n3. **Start services**\n```bash\ndocker compose up --build\n```\n\n4. **Run database migrations**\n```bash\ndocker compose exec backend alembic upgrade head\n```\n\n5. **Access the application**\n- API documentation: http://localhost:8000/docs\n- MCP endpoint: http://localhost:8000/mcp\n\n### Run Locally with uv\n\n```bash\ncd backend\ncp .env.example .env\n# Edit .env with your database settings\n\nuv sync\ndocker compose up -d db\nuv run alembic upgrade head\nuv run uvicorn app.main:app --reload\n```\n\n### Use with AI Agents\n\n#### Quick Start: Install as a Skill\n```bash\nnpx skills add vaddisrinivas/voltsnip/voltsnip-skill\n```\nThis is the install path that drives skills.sh listing. See `docs/skills-sh-listing.md` for details.\n\n#### Optional: Fetch SKILL.md via npm\n```bash\nnpx @vaddisrinivas/voltsnip-skill --output ./SKILL.md\n```\nThis is a convenience for local copy only (it does not affect skills.sh ranking).\n\n#### Claude Desktop Integration (Hosted MCP)\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"voltsnip\": {\n      \"url\": \"https://voltsnip-api.thetechcruise.com/mcp\",\n      \"transport\": \"http\"\n    }\n  }\n}\n```\nIf your client expects SSE, set `\"transport\": \"sse\"` with the same URL.\n\n#### VS Code (Cline/Cursor) (Hosted MCP)\n\nAdd to your MCP settings file (typically `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/mcpSettings.json`):\n```json\n{\n  \"voltsnip\": {\n    \"url\": \"https://voltsnip-api.thetechcruise.com/mcp\",\n    \"transport\": \"http\"\n  }\n}\n```\n\nSee [voltsnip-skill/README.md](voltsnip-skill/README.md) for detailed integration guides.\n\n## How It Works\n\n**Stack:**\n- Backend: Python 3.12, FastAPI, SQLAlchemy 2.0\n- Database: PostgreSQL 16 with pgvector for semantic search\n- Embeddings: fastembed (runs locally, no external API calls)\n- Interfaces: RESTful HTTP API + MCP server\n\n**Search flow:**\n1. Query is converted to an embedding vector using fastembed\n2. PostgreSQL's pgvector extension finds semantically similar snippets\n3. Results are ranked by a combination of similarity score, votes, and usage\n4. Snippets include metadata (language, tags, author) for context\n\n## Use Cases\n\n**Common development tasks:**\n- Need a retry decorator with exponential backoff? Search \"retry exponential backoff\"\n- Parsing structured data from text? Find regex patterns others have refined\n- Setting up a common config pattern? Retrieve a template someone's already debugged\n\n**Agent workflows:**\n- Agent encounters a known problem and searches for a proven solution\n- Agent creates a working implementation and saves it for future reuse\n- Different agents (or runs) share knowledge without requiring conversation history\n\n## Roadmap\n\n**Near-term improvements:**\n- Automated secret detection to prevent credential leaks\n- Code quality checks on submission (linting, basic static analysis)\n- Better snippet versioning and forking\n\n**Future exploration:**\n- Private team instances or namespaces\n- CLI tool for terminal-based search and submission\n- Editor plugins (VS Code, JetBrains)\n- GitHub integration for importing from gists or repos\n\n## Contributing\n\nThis is a personal project, but contributions are welcome:\n- Bug fixes and performance improvements\n- Better search relevance or ranking algorithms\n- Documentation improvements\n- New integrations or tooling\n\nPlease keep PRs focused and avoid submitting proprietary or sensitive code to the public instance.\n\n## Repository Structure\n\n```\nvoltsnip/\n├── backend/          # FastAPI application and MCP server\n├── frontend/         # Web interface (HTML/CSS/JS)\n├── voltsnip-skill/   # MCP skill documentation and references\n├── scripts/          # Build/deploy scripts\n└── local_storage/    # Local dev storage (optional)\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n**Connect:** [LinkedIn](https://www.linkedin.com/in/srinivasvaddi)  \n**Note:** Significant portions of this project were developed with assistance from AI coding tools.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaddisrinivas%2Fvoltsnip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaddisrinivas%2Fvoltsnip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaddisrinivas%2Fvoltsnip/lists"}