{"id":44376644,"url":"https://github.com/kylebrodeur/universal-agent-context","last_synced_at":"2026-02-11T21:11:48.240Z","repository":{"id":336105040,"uuid":"1122995016","full_name":"kylebrodeur/universal-agent-context","owner":"kylebrodeur","description":"Universal context system for AI agents: discover, translate, and manage agent skills across formats. Includes MCP server, CLI, and Python library.","archived":false,"fork":false,"pushed_at":"2026-02-02T23:31:32.000Z","size":1119,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-03T10:27:06.957Z","etag":null,"topics":["agent-context","agent-skills","agents","ai","ai-tools","cli","context-management","docker","llm","mcp","mcp-server","model-context-protocol","multi-agent-systems","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kylebrodeur.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2025-12-26T01:49:16.000Z","updated_at":"2026-02-02T20:24:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kylebrodeur/universal-agent-context","commit_stats":null,"previous_names":["kylebrodeur/universal-agent-context"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kylebrodeur/universal-agent-context","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebrodeur%2Funiversal-agent-context","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebrodeur%2Funiversal-agent-context/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebrodeur%2Funiversal-agent-context/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebrodeur%2Funiversal-agent-context/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kylebrodeur","download_url":"https://codeload.github.com/kylebrodeur/universal-agent-context/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebrodeur%2Funiversal-agent-context/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29345433,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T20:11:40.865Z","status":"ssl_error","status_checked_at":"2026-02-11T20:10:41.637Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["agent-context","agent-skills","agents","ai","ai-tools","cli","context-management","docker","llm","mcp","mcp-server","model-context-protocol","multi-agent-systems","python"],"created_at":"2026-02-11T21:11:43.189Z","updated_at":"2026-02-11T21:11:48.229Z","avatar_url":"https://github.com/kylebrodeur.png","language":"Python","readme":"# Universal Agent Context System (UACS)\n\n**Version 0.3.0** - Semantic Conversations \u0026 Knowledge Extraction\n\n[![PyPI](https://img.shields.io/badge/pypi-v0.3.0-blue)](https://pypi.org/project/universal-agent-context/)\n[![Tests](https://img.shields.io/badge/tests-190%2B%20passing-brightgreen)]()\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue)]()\n[![License](https://img.shields.io/badge/license-MIT-blue)]()\n\n\u003e **TL;DR:** Universal context middleware for AI agents with semantic conversation tracking and knowledge extraction. One source of truth → 5+ formats. Perfect recall with smart search. Package management for skills + MCP. Works with Claude, Cursor, Windsurf, Cline, or your own Python code.\n\n---\n\n## Why UACS?\n\nBuilding AI agent systems today means juggling multiple formats, wasting tokens, and losing context between sessions. **UACS solves this.**\n\n**In 30 seconds:**\n- 🔄 Write once → Deploy to Claude, Cursor, Cline, Gemini, Copilot\n- 🧠 **NEW v0.3.0:** Semantic API for structured conversations and knowledge\n- 🔍 **NEW v0.3.0:** Natural language search across all context\n- 📝 **NEW v0.3.0:** Automatic decision and convention extraction\n- 🎯 **NEW v0.3.0:** Claude Code hooks for real-time capture\n- 🗜️ Never lose context with automatic deduplication (15% immediate savings)\n- 🛡️ Proactive compaction prevention for Claude Code (95%+ success rate)\n- 🤖 Local LLM tagging via transformers (zero API cost, better quality)\n- 📊 LangSmith-style trace visualization (debug any session)\n- 📦 Package management for skills + MCP servers (GitHub, Git, local)\n- ⚡ Python API + CLI + MCP server = works everywhere\n\n**What makes UACS different:** It's **middleware**, not another agent tool. Claude Desktop gets better when you add UACS. So does Cursor. So does your custom Python agent.\n\n---\n\n## What's New in v0.3.0\n\n### Semantic API\n\nUACS v0.3.0 introduces a powerful semantic API for structured conversation tracking and knowledge extraction:\n\n**Structured Conversations:**\n- Track user messages, assistant responses, and tool executions\n- Automatic embedding generation for semantic search\n- Session-based organization with turn tracking\n\n**Knowledge Extraction:**\n- Capture architectural decisions with rationale\n- Extract project conventions and patterns\n- Store cross-session learnings\n- Track code artifacts and their purpose\n\n**Semantic Search:**\n- Natural language queries across all stored context\n- \"How did we implement authentication?\"\n- Type-specific filtering (messages, decisions, conventions)\n- Relevance-ranked results\n\n**Claude Code Integration:**\n- Automatic capture via hooks (UserPromptSubmit, PostToolUse, SessionEnd)\n- Real-time context storage (crash-resistant)\n- Decision and convention extraction from conversations\n\nSee [Migration Guide](docs/MIGRATION.md) to upgrade from v0.2.x.\n\n---\n\n## Installation\n\nChoose the installation method that best fits your workflow:\n\n| Method | Best For | Prerequisite |\n| :--- | :--- | :--- |\n| **Python (pip)** | Developers integrating UACS into Python projects | Python 3.11+ |\n| **uvx** | Quick, temporary usage without installing dependencies | `uv` installed |\n| **[Binary](docs/guides/MCP_SERVER_BINARY.md)** | Standalone usage, no Python environment needed | None |\n| **[Docker](docs/guides/MCP_SERVER_DOCKER.md)** | Server deployments, team environments | Docker |\n\n### Quick Start (Python)\n\n```bash\n# Option 1: From source (Current - Week 1)\ngit clone https://github.com/kylebrodeur/universal-agent-context\ncd universal-agent-context\nuv sync                    # Or: pip install -e .\n\n# Option 2: PyPI (Coming Week 3)\npip install universal-agent-context\n\n# Option 3: One-liner (Coming Week 2)\nuvx universal-agent-context serve\n\n# Initialize project\nuv run uacs context init   # Creates .state/context/ directory\nuv run uacs memory init    # Creates .state/memory/ directory\n\n# Optional: For local LLM tagging (better topic extraction)\npip install transformers torch  # ~2GB download on first use\n```\n\n### Claude Code Plugin\n\n**v0.3.0: Semantic capture + proactive compaction prevention + real-time storage:**\n\n```bash\n# Install semantic plugin\ncp .claude-plugin/plugin-semantic.json ~/.claude/plugin.json\ncp .claude-plugin/hooks/*.py ~/.claude/hooks/\nchmod +x ~/.claude/hooks/*.py\n\n# Optional: Install transformers for better topic extraction\npip install transformers torch\n```\n\n**v0.3.0 Features:**\n- 📝 **Semantic Capture**: Automatically captures user messages, tool uses, decisions, and conventions\n- 🔍 **Natural Language Search**: Query stored context with \"how did we implement auth?\"\n- 🧠 **Knowledge Extraction**: Identifies decisions and conventions from conversations\n- 🎯 **Structured Storage**: All data stored with embeddings for semantic search\n\n**v0.2.0 Features:**\n- 🛡️ **Compaction Prevention**: Monitors context, compresses at 50% (before Claude's 75% threshold) - 95%+ success\n- 🤖 **Local LLM Tagging**: Uses TinyLlama (1.1B) for topic extraction - zero API cost\n- 💾 **Crash-Resistant**: Real-time storage via PostToolUse hook\n- 🔄 **Auto-Context**: Injects previous context on session resume\n\n**See:** [Hooks Guide](.claude-plugin/HOOKS_GUIDE.md) | [Migration Guide](docs/MIGRATION.md) | [API Reference](docs/API_REFERENCE.md)\n\n---\n\n## CLI Demo\n\n```bash\n# Package management\n$ uacs packages install anthropic/skills-testing\n✅ Installed to .agent/skills/testing/\n\n# Context compression\n$ uacs context stats\n📊 45,234 tokens → 38,449 (15% reduction)\n💰 Savings: $0.07/call\n\n# Memory search\n$ uacs memory search \"testing\"\n🔍 Found 3 relevant memories (scores: 0.92, 0.87, 0.81)\n```\n\n**See also:** [CLI Reference](docs/CLI_REFERENCE.md) | [Examples](examples/)\n\n---\n\n## Web UI (NEW v0.3.0)\n\nModern Next.js web application for exploring UACS data with semantic search and knowledge browsing. Bundled into a single command:\n\n```bash\n# Single command - bundled UI!\nuv run uacs web\n\n# Or with custom options:\nuv run uacs web --port 8081 --host localhost\n\n# Open browser\nopen http://localhost:8081\n```\n\n💡 **Bundled Architecture:** The Next.js frontend (static export) is served directly from FastAPI - no separate frontend server needed!\n\n**Features:**\n- 🔍 **Semantic Search** - Natural language search across all content with type filters\n- 📅 **Timeline View** - Chronological session events with user/assistant/tool interactions\n- 📚 **Knowledge Browser** - Explore decisions, conventions, learnings, and artifacts\n- 🔬 **Session Traces** - Expandable session cards with full execution timelines\n- 🎨 **Modern UI** - Built with Next.js 15, TypeScript, and shadcn/ui\n- 🌙 **Dark Mode** - System preference support\n\n**See:** [Web UI Documentation](uacs-web-ui/README.md) | [Implementation Complete](./.github/NEXT_JS_WEB_UI_COMPLETE.md)\n\n---\n\n## The Problem\n\nBuilding with AI agents today means:\n\n- 😫 **Context switching** - Maintaining separate configs for Claude, Gemini, Copilot (SKILLS.md, .cursorrules, .clinerules, AGENTS.md)\n- 😫 **Copy-paste errors** - Manually syncing instructions across formats\n- 😫 **Token waste** - Large contexts cost money, no intelligent compression\n- 😫 **Tool isolation** - Each agent tool manages skills/context separately\n- 😫 **Memory fragmentation** - Context lost between agent sessions\n\n## The Solution\n\nUACS provides three integration points:\n\n1. **Python Library** - Direct use by developers building agent applications\n2. **CLI Tool** - `uacs` commands for local development and scripting  \n3. **MCP Server** - Expose UACS capabilities to Claude Desktop, Cursor, Windsurf, Cline\n\n**The Result:**\n\u003e Your existing tools get package management, format conversion, perfect recall with deduplication, and persistent memory - without changing how you work.\n\n---\n\n## Use Cases\n\n### 1. Multi-Tool Development\n**Scenario:** You build agents for both Claude Desktop and Cursor IDE.\n\n**Before UACS:**\n```\n.cursorrules          (Cursor config)\nSKILLS.md             (Claude config)\n.clinerules           (Cline config)\n# Manual sync, 3x maintenance\n```\n\n**With UACS:**\n```bash\n# Write once in SKILLS.md\nuacs skills convert --to cursorrules  # Auto-generate .cursorrules\nuacs skills convert --to clinerules   # Auto-generate .clinerules\n# One source, zero sync errors\n```\n\n### 2. Token Cost Optimization\n**Scenario:** Your agent uses 10,000 tokens per call at $0.01/1K tokens.\n\n**Before UACS:**\n- Cost per call: $0.10\n- 100 calls/day: $10/day = $300/month\n\n**With UACS (v0.1.0):**\n```python\ncontext = uacs.get_compressed_context(max_tokens=8500)  # Smart retrieval + deduplication\n# 15% deduplication savings + perfect recall\n# Cost per call: $0.085\n# 100 calls/day: $8.50/day = $255/month\n# Savings: $45/month (15%)\n# Plus: 2 hours/week saved (no re-explaining after context resets)\n```\n\n### 3. Package Management\n**Scenario:** You need testing capabilities for your agent.\n\n**Before UACS:**\n```\n# Search GitHub manually\n# Clone repos\n# Copy-paste configs\n# Update manually when changes occur\n```\n\n**With UACS:**\n```bash\nuacs packages install anthropic/skills-testing\n# Installed in .agent/skills/ with metadata tracking\n# Works with GitHub repos, Git URLs, or local paths\n```\n\n### 4. Persistent Agent Memory\n**Scenario:** Your agent should remember project conventions across sessions.\n\n**With UACS:**\n```python\n# Session 1: Agent learns convention\nuacs.memory.add(\"Use pytest-asyncio for async tests\", scope=\"project\")\n\n# Session 2: Different agent, same project\nrelevant = uacs.memory.search(\"testing\")\n# Returns: \"Use pytest-asyncio for async tests\"\n# Zero manual context management\n```\n\n---\n\n## What Makes UACS Different\n\nUACS is **middleware**, not another agent tool. It provides format translation, context compression, package management, persistent memory, and MCP server integration in one package - the only solution offering this complete feature set.\n\n---\n\n## Quick Start\n\n### Basic Usage (v0.3.0 Semantic API)\n\n```python\nfrom uacs import UACS\nfrom pathlib import Path\n\n# Initialize\nuacs = UACS(project_path=Path(\".\"))\n\n# Track conversation\nuser_msg = uacs.add_user_message(\n    content=\"Help me implement JWT authentication\",\n    turn=1,\n    session_id=\"session_001\",\n    topics=[\"security\", \"feature\"]\n)\n\nassistant_msg = uacs.add_assistant_message(\n    content=\"I'll help you implement JWT. First, let's...\",\n    turn=1,\n    session_id=\"session_001\",\n    tokens_in=42,\n    tokens_out=156\n)\n\n# Capture decisions\ndecision = uacs.add_decision(\n    question=\"Which auth method should we use?\",\n    decision=\"JWT tokens\",\n    rationale=\"Stateless, scalable, works with microservices\",\n    session_id=\"session_001\",\n    alternatives=[\"Session-based (doesn't scale)\", \"OAuth2 (overkill)\"]\n)\n\n# Search semantically\nresults = uacs.search(\"how did we implement authentication?\", limit=10)\nfor result in results:\n    print(f\"[{result.metadata['type']}] {result.text[:100]}...\")\n    print(f\"Relevance: {result.similarity:.2f}\\n\")\n```\n\n**See also:** [Full Quickstart Guide](QUICKSTART.md) | [API Reference](docs/API_REFERENCE.md) | [Examples](examples/)\n\n---\n\n### Three Ways to Use UACS\n\n#### 1. Python Library\n\n```python\nfrom uacs import UACS\nfrom pathlib import Path\n\n# Initialize\nuacs = UACS(project_path=Path.cwd())\n\n# Install packages\nuacs.packages.install(\"anthropic/skills-testing\")  # From GitHub\nuacs.packages.install(\"/path/to/local/skill\")      # From local path\n\n# Get compressed context\ncontext = uacs.get_compressed_context(\n    topic=\"testing\",\n    max_tokens=4000  # Smart deduplication + topic filtering\n)\n\n# Memory management\nuacs.memory.add(\"Important: Always use pytest-asyncio for async tests\")\nrelevant = uacs.memory.search(\"async testing\")\n```\n\n#### 2. CLI Tool\n\n```bash\n# Package management\nuacs packages install anthropic/skills-testing\nuacs packages list\nuacs packages remove pytest-skill\n\n# Format conversion\nuacs skills convert --from cursorrules --to skills\n\n# Context management\nuacs context stats\nuacs context compress --max-tokens 4000\n\n# Memory\nuacs memory add \"Important insight\"\nuacs memory search \"relevant topic\"\n```\n\n#### 3. MCP Server (For Claude Desktop, Cursor, Windsurf)\n\n```bash\n# Start MCP server\nuacs serve\n\n# Or with uvx (one-liner)\nuvx universal-agent-context serve\n```\n\n**Configure in Claude Desktop:**\n```json\n// ~/Library/Application Support/Claude/claude_desktop_config.json\n{\n  \"mcpServers\": {\n    \"uacs\": {\n      \"command\": \"uacs\",\n      \"args\": [\"serve\"],\n      \"env\": {\n        \"UACS_PROJECT_PATH\": \"/path/to/your/project\"\n      }\n    }\n  }\n}\n```\n\n**Now Claude Desktop can:**\n- Manage packages from GitHub, Git, or local paths\n- Convert between formats on-the-fly\n- Compress large contexts automatically\n- Access your project memory\n- Install skills directly from conversation\n\n---\n\n## Core Features\n\n### 🔄 Format Translation\n\n**The Problem:** You write for Claude (SKILLS.md), but also need Cursor (.cursorrules) and Cline (.clinerules) configs.\n\n**The Solution:** Write once, deploy everywhere.\n\n```bash\n# Convert .cursorrules to SKILLS.md\nuv run uacs skills convert --from cursorrules --to skills\n\n# Or in Python:\nfrom uacs.adapters import FormatAdapterRegistry\n\nadapter = FormatAdapterRegistry.get_adapter(\"cursorrules\")\ncontent = adapter.parse(Path(\".cursorrules\").read_text())\nskills_format = content.to_system_prompt()\n```\n\n**Supported Formats:**\n- ✅ **Agent Skills (SKILLS.md)** - Anthropic standard ([spec](https://docs.anthropic.com/en/docs/build-with-claude/agent-skills))\n- ✅ **AGENTS.md** - Project context standard ([spec](https://github.com/openai/agents))\n- ✅ **.cursorrules** - Cursor IDE format\n- ✅ **.clinerules** - Cline VSCode extension\n- 🚧 **ADK Agent Config** - Google ADK format (Coming Phase 7)\n\n**Quality validation included:** All conversions verify structure, check for required fields, score quality.\n\n### 🗜️ Context Compression\n\n**The Problem:** Large contexts = high costs. A 10K token call costs $0.10. At scale, this adds up fast.\n\n**The Solution:** Smart context management with perfect recall.\n\n**Current Implementation (v0.1.0):**\n1. **Deduplication** - Hash-based, automatic (15% savings)\n2. **Quality Filtering** - Remove noise, keep signal\n3. **Topic-Based Retrieval** - Focus on relevant context\n4. **Exact Storage** - 100% fidelity, zero information loss\n\n**Coming in v0.2.0:**\n5. **LLM Summarization** - Claude Haiku for intelligent compression\n6. **Vector Embeddings** - Semantic similarity search\n7. **Knowledge Graph** - Context relationship traversal\n8. **Target: 70%+ compression** with zero information loss\n\n**Real-world Impact (v0.1.0):**\n```python\n# Deduplication savings:\n- Original context: 10,000 tokens\n- After deduplication: 8,500 tokens (15% savings)\n- Cost per call: $0.085 (vs $0.10)\n- 100 calls/day: $8.50/day vs $10/day\n- Monthly savings: $45 (15%)\n\n# Plus time savings:\n- Context never lost = no re-explaining\n- Save ~2 hours/week for active developers\n```\n\n**Usage:**\n```python\n# Automatic compression\ncontext = uacs.get_compressed_context(\n    topic=\"security review\",  # Filter by topic\n    max_tokens=4000,          # Target size\n    agent=\"claude\"            # Filter by agent (optional)\n)\n\n# Check what you saved\nstats = uacs.get_token_stats()\nprint(f\"Saved: {stats['tokens_saved_by_compression']} tokens\")\nprint(f\"Ratio: {stats['compression_ratio']}\")\n```\n\n### 📦 Package Management\n\n**The Problem:** Skills scattered across GitHub. MCP servers in different repositories. Manual cloning and installation.\n\n**The Solution:** Simple package manager modeled after GitHub CLI extensions.\n\n```bash\n# Install from GitHub\nuv run uacs packages install anthropic/skills-testing\n\n# Install from Git URL\nuv run uacs packages install https://github.com/owner/repo.git\n\n# Install from local path\nuv run uacs packages install /path/to/skill\n\n# List installed packages\nuv run uacs packages list\n\n# Update packages\nuv run uacs packages update\n```\n\n**Installation sources:**\n- ✅ GitHub repositories (`owner/repo`)\n- ✅ Git URLs (HTTPS or SSH)\n- ✅ Local paths (absolute or relative)\n\n**Installation tracking:**\n```bash\n# Install package\nuv run uacs packages install anthropic/skills-testing\n\n# Stored in: .agent/skills/testing/\n# Metadata: .agent/skills/.installed.json (tracks source, version, installed date)\n\n# Uninstall\nuv run uacs packages remove testing\n```\n\n### 🧠 Memory System\n\n**The Problem:** Agents forget project conventions between sessions. You repeat instructions constantly.\n\n**The Solution:** Persistent memory with project and global scopes.\n\n```bash\n# Initialize\nuv run uacs memory init\n\n# Add project-specific memory\nuv run uacs memory add \"Use pytest-asyncio for async tests\" --scope project\n\n# Add global memory (all projects)\nuv run uacs memory add \"Prefer composition over inheritance\" --scope global\n\n# Search with semantic similarity\nuv run uacs memory search \"testing patterns\"\n# Returns: Relevant memories with similarity scores\n\n# Python API\nfrom uacs import UACS\nuacs = UACS()\n\n# Add memory programmatically\nuacs.memory.add(\n    \"Critical: Always validate input before processing\",\n    scope=\"project\",\n    tags=[\"security\", \"validation\"]\n)\n\n# Search by topic\nresults = uacs.memory.search(\"security\", scope=\"project\")\nfor memory in results:\n    print(f\"{memory.content} (score: {memory.score})\")\n```\n\n**Storage:**\n- Project scope: `.state/memory/project/`\n- Global scope: `~/.config/uacs/memory/global/`\n- Format: JSON with metadata (timestamp, tags, usage count)\n\n---\n\n## API Reference (v0.3.0)\n\n### Conversation Methods\n\nTrack structured conversation elements with automatic embedding generation:\n\n- **`add_user_message(content, turn, session_id, topics)`** - Track user prompts\n- **`add_assistant_message(content, turn, session_id, tokens_in, tokens_out, model)`** - Track assistant responses\n- **`add_tool_use(tool_name, tool_input, tool_response, turn, session_id, latency_ms, success)`** - Track tool executions\n\n### Knowledge Methods\n\nCapture architectural knowledge with semantic indexing:\n\n- **`add_decision(question, decision, rationale, session_id, alternatives, decided_by, topics)`** - Capture architectural decisions\n- **`add_convention(content, topics, source_session, confidence)`** - Capture project conventions and patterns\n- **`add_learning(pattern, learned_from, category, confidence)`** - Capture cross-session learnings\n- **`add_artifact(type, path, description, created_in_session, topics)`** - Track code artifacts\n\n### Search Method\n\nNatural language semantic search across all stored context:\n\n- **`search(query, types, min_confidence, session_id, limit)`** - Search with natural language queries\n  - Returns ranked results by relevance\n  - Filter by type (user_message, assistant_message, tool_use, convention, decision, learning, artifact)\n  - Filter by session or confidence threshold\n\n### Statistics Methods\n\nAccess system statistics and capabilities:\n\n- **`get_stats()`** - Get comprehensive UACS statistics (entries, tokens, compression, semantic data)\n- **`get_capabilities(agent)`** - Get available capabilities for an agent\n- **`get_token_stats()`** - Get token usage and compression statistics\n\n**Complete documentation:** [API Reference](docs/API_REFERENCE.md)\n\n---\n\n## Migrating to v0.3.0\n\nUACS v0.3.0 is **backward compatible**. Existing code using `add_to_context()` will continue to work but is deprecated.\n\n### Quick Migration\n\n**Old API (deprecated):**\n```python\nuacs.add_to_context(\n    key=\"claude\",\n    content=\"Implemented feature\",\n    topics=[\"dev\"]\n)\n```\n\n**New Semantic API (recommended):**\n```python\nuacs.add_convention(\n    content=\"Implemented feature\",\n    topics=[\"dev\"],\n    confidence=1.0\n)\n```\n\n### Migration Benefits\n\n- ✅ **Better Search:** Natural language queries instead of topic-only filtering\n- ✅ **Structured Data:** Explicit types (decisions, conventions, learnings) instead of generic context\n- ✅ **Automatic Embeddings:** Semantic indexing for all entries\n- ✅ **Hooks Integration:** Seamless Claude Code integration with automatic capture\n- ✅ **Future-Proof:** Ready for v0.5.0+ (add_to_context removed in v0.5.0)\n\n**Complete migration guide:** [Migration Guide](docs/MIGRATION.md)\n\n---\n\n## Documentation\n\n**Getting Started:**\n- 🚀 [Quick Start](#quick-start) - 5-minute tutorial (above)\n- 📦 Installation - See [Quick Start](#installation) section\n- 🎯 [Use Cases](#use-cases) - Real-world scenarios\n\n**Integrations:**\nUACS works with popular MCP clients out of the box:\n- 🤖 [Claude Desktop](docs/integrations/CLAUDE_DESKTOP.md) - Complete setup guide with binary + Docker\n- ✏️ [Cursor](docs/integrations/CURSOR.md) - Integration with inline chat and Composer\n- 🌊 [Windsurf](docs/integrations/WINDSURF.md) - Cascade AI integration guide\n- 📚 [All Integrations](docs/features/INTEGRATIONS.md) - Overview, troubleshooting, and advanced configs\n\n**User Guides:**\n- [Migration Guide](docs/MIGRATION.md) - Upgrade from v0.2.x to v0.3.0 semantic API\n- [API Reference](docs/API_REFERENCE.md) - Complete v0.3.0 API documentation with examples\n- [Hooks Guide](.claude-plugin/HOOKS_GUIDE.md) - Claude Code hooks for automatic capture\n- [Library Guide](docs/LIBRARY_GUIDE.md) - Complete Python API reference\n- [CLI Reference](docs/CLI_REFERENCE.md) - All command documentation\n- [MCP Server Setup](docs/guides/MCP_SERVER_SETUP.md) - MCP integration for Claude/Cursor/Windsurf\n\n**Technical Deep Dives:**\n- [Adapters](docs/features/ADAPTERS.md) - Format translation architecture\n- [Context Management](docs/features/CONTEXT.md) - Compression algorithms\n- [Package Management](docs/features/PACKAGES.md) - Installation and management system\n\n**Examples:**\nAll examples use v0.3.0 semantic API and take ~15 minutes total:\n- [01_semantic_basics.py](examples/01_semantic_basics.py) - Core API (5 min)\n- [02_claude_code_integration.py](examples/02_claude_code_integration.py) - Hooks \u0026 auto-capture (5 min)\n- [03_web_ui.py](examples/03_web_ui.py) - Web UI visualization (3 min)\n- [04_search_and_knowledge.py](examples/04_search_and_knowledge.py) - Advanced patterns (2 min)\n- [See examples/README.md](examples/README.md) - Full guide with learning paths\n\n**Development:**\n- [Contributing](CONTRIBUTING.md) - How to contribute\n\n---\n\n## Requirements\n\n- **Python:** 3.11 or higher\n- **Optional:** Node.js (for MCP filesystem server)\n- **Optional:** Docker (for containerized MCP deployment)\n\n**Installation via `uv` (recommended):**\n```bash\n# Install uv if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone and install UACS\ngit clone https://github.com/kylebrodeur/universal-agent-context\ncd universal-agent-context\nuv sync\n```\n\n---\n\n## Development\n\n**Setup:**\n```bash\n# Clone repository\ngit clone https://github.com/kylebrodeur/universal-agent-context.git\ncd universal-agent-context\n\n# Install with dev dependencies\nuv sync  # Or: pip install -e \".[dev]\"\n\n# Run tests\nuv run pytest                # All tests\nuv run pytest -n auto        # Parallel (faster)\nuv run pytest --cov=src      # With coverage\n\n# Code quality\nuv run ruff format .         # Format code\nuv run ruff check --fix .    # Lint and fix\n```\n\n**Contributing:**\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## Built on Standards\n\nUACS implements and extends these community standards:\n\n**[Agent Skills](https://agentskills.io)** - Universal skill format by Anthropic\nUACS supports the Agent Skills specification for skill packaging and discovery.\n\n**[AGENTS.md](https://agents.md)** - Open format for agent context\nUACS reads and writes AGENTS.md format, enabling format translation across tools.\n\n---\n\n## Related Projects\n\n### Complementary Tools\n\n**[claude-code-transcripts](https://github.com/simonw/claude-code-transcripts)** - Publish sessions to HTML/Gist\nExport and share your Claude Code sessions as beautiful web pages. Pairs with UACS trace visualization.\n\n**[GrepAI](https://github.com/yoanbernabeu/grepai)** - Semantic code search (100% local)\nNatural language code search as MCP server. Use together: GrepAI finds code, UACS compresses and manages it as context.\n\n### Content Sources\n\n**[OpenAI Skills](https://github.com/openai/skills)** - Curated skills catalog\nOfficial Codex skills collection. Install via UACS: `uacs packages install openai/skills-[name]`\n\n### Alternative Approaches\n\n**[memcord](https://github.com/ukkit/memcord)** - Privacy-first MCP memory server\nConversation history with summarization. Alternative to UACS's trace visualization - different storage model (MCP server vs JSONL) and different focus (summarization vs compression analytics).\n\n**[claude-mem](https://github.com/thedotmack/claude-mem)** - Session memory with web UI\nSimilar to UACS trace visualization but with SQLite + Chroma backend. UACS offers broader infrastructure (compaction prevention, format translation, MCP server, packages) while claude-mem provides dedicated memory browsing interface.\n\n**[openskills](https://github.com/numman-ali/openskills)** - Universal skills loader (Node.js)\nProgressive disclosure approach to skill loading. Alternative to UACS's compression strategy, Node.js vs Python.\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details\n\n---\n\n## Acknowledgments\n\n- **Anthropic** - Agent Skills specification ([docs](https://docs.anthropic.com/en/docs/build-with-claude/agent-skills)) and MCP protocol\n- **Google** - Agent Development Kit (ADK)\n- **OpenAI** - AGENTS.md standard\n- **Community** - Skills contributors at [agentskills.io](https://agentskills.io) and [Smithery](https://smithery.ai)\n\n---\n\n**Version:** 0.3.0 | **License:** MIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylebrodeur%2Funiversal-agent-context","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkylebrodeur%2Funiversal-agent-context","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylebrodeur%2Funiversal-agent-context/lists"}