uacs

Universal Agent Context System (UACS)

Version 0.3.0 - Semantic Conversations & Knowledge Extraction

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.

---

Why UACS?

Building AI agent systems today means juggling multiple formats, wasting tokens, and losing context between sessions. UACS solves this.

In 30 seconds:

• 🔄 Write once → Deploy to Claude, Cursor, Cline, Gemini, Copilot
• 🧠 NEW v0.3.0: Semantic API for structured conversations and knowledge
• 🔍 NEW v0.3.0: Natural language search across all context
• 📝 NEW v0.3.0: Automatic decision and convention extraction
• 🎯 NEW v0.3.0: Claude Code hooks for real-time capture
• 🗜️ Never lose context with automatic deduplication (15% immediate savings)
• 🛡️ Proactive compaction prevention for Claude Code (95%+ success rate)
• 🤖 Local LLM tagging via transformers (zero API cost, better quality)
• 📊 LangSmith-style trace visualization (debug any session)
• 📦 Package management for skills + MCP servers (GitHub, Git, local)
• ⚡ Python API + CLI + MCP server = works everywhere

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.

---

What's New in v0.3.0

Semantic API

UACS v0.3.0 introduces a powerful semantic API for structured conversation tracking and knowledge extraction:

Structured Conversations:

• Track user messages, assistant responses, and tool executions
• Automatic embedding generation for semantic search
• Session-based organization with turn tracking

Knowledge Extraction:

• Capture architectural decisions with rationale
• Extract project conventions and patterns
• Store cross-session learnings
• Track code artifacts and their purpose

Semantic Search:

• Natural language queries across all stored context
• "How did we implement authentication?"
• Type-specific filtering (messages, decisions, conventions)
• Relevance-ranked results

Claude Code Integration:

• Automatic capture via hooks (UserPromptSubmit, PostToolUse, SessionEnd)
• Real-time context storage (crash-resistant)
• Decision and convention extraction from conversations

See Migration Guide to upgrade from v0.2.x.

---

Installation

Choose the installation method that best fits your workflow:

Method	Best For	Prerequisite
Python (pip)	Developers integrating UACS into Python projects	Python 3.11+
uvx	Quick, temporary usage without installing dependencies	uv installed
Binary	Standalone usage, no Python environment needed	None
Docker	Server deployments, team environments	Docker

Quick Start (Python)

# Option 1: From source (Current - Week 1)
git clone https://github.com/kylebrodeur/universal-agent-context
cd universal-agent-context
uv sync                    # Or: pip install -e .

# Option 2: PyPI (Coming Week 3)
pip install universal-agent-context

# Option 3: One-liner (Coming Week 2)
uvx universal-agent-context serve

# Initialize project
uv run uacs context init   # Creates .state/context/ directory
uv run uacs memory init    # Creates .state/memory/ directory

# Optional: For local LLM tagging (better topic extraction)
pip install transformers torch  # ~2GB download on first use

Claude Code Plugin

v0.3.0: Semantic capture + proactive compaction prevention + real-time storage:

# Install semantic plugin
cp .claude-plugin/plugin-semantic.json ~/.claude/plugin.json
cp .claude-plugin/hooks/*.py ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.py

# Optional: Install transformers for better topic extraction
pip install transformers torch

v0.3.0 Features:

• 📝 Semantic Capture: Automatically captures user messages, tool uses, decisions, and conventions
• 🔍 Natural Language Search: Query stored context with "how did we implement auth?"
• 🧠 Knowledge Extraction: Identifies decisions and conventions from conversations
• 🎯 Structured Storage: All data stored with embeddings for semantic search