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

v0.2.0 Features:

• 🛡️ Compaction Prevention: Monitors context, compresses at 50% (before Claude's 75% threshold) - 95%+ success
• 🤖 Local LLM Tagging: Uses TinyLlama (1.1B) for topic extraction - zero API cost
• 💾 Crash-Resistant: Real-time storage via PostToolUse hook
• 🔄 Auto-Context: Injects previous context on session resume

See: Hooks Guide | Migration Guide | API Reference

---

CLI Demo

# Package management
$ uacs packages install anthropic/skills-testing
✅ Installed to .agent/skills/testing/

# Context compression
$ uacs context stats
📊 45,234 tokens → 38,449 (15% reduction)
💰 Savings: $0.07/call

# Memory search
$ uacs memory search "testing"
🔍 Found 3 relevant memories (scores: 0.92, 0.87, 0.81)

See also: CLI Reference | Examples

---

Web UI (NEW v0.3.0)

Modern Next.js web application for exploring UACS data with semantic search and knowledge browsing. Bundled into a single command:

# Single command - bundled UI!
uv run uacs web

# Or with custom options:
uv run uacs web --port 8081 --host localhost

# Open browser
open http://localhost:8081

💡 Bundled Architecture: The Next.js frontend (static export) is served directly from FastAPI - no separate frontend server needed!

Features:

• 🔍 Semantic Search - Natural language search across all content with type filters
• 📅 Timeline View - Chronological session events with user/assistant/tool interactions
• 📚 Knowledge Browser - Explore decisions, conventions, learnings, and artifacts
• 🔬 Session Traces - Expandable session cards with full execution timelines
• 🎨 Modern UI - Built with Next.js 15, TypeScript, and shadcn/ui
• 🌙 Dark Mode - System preference support

See: Web UI Documentation | Implementation Complete

---

The Problem

Building with AI agents today means:

• 😫 Context switching - Maintaining separate configs for Claude, Gemini, Copilot (SKILLS.md, .cursorrules, .clinerules, AGENTS.md)
• 😫 Copy-paste errors - Manually syncing instructions across formats
• 😫 Token waste - Large contexts cost money, no intelligent compression
• 😫 Tool isolation - Each agent tool manages skills/context separately
• 😫 Memory fragmentation - Context lost between agent sessions

The Solution

UACS provides three integration points:

1. Python Library - Direct use by developers building agent applications
2. CLI Tool - uacs commands for local development and scripting
3. MCP Server - Expose UACS capabilities to Claude Desktop, Cursor, Windsurf, Cline

The Result:

Your existing tools get package management, format conversion, perfect recall with deduplication, and persistent memory - without changing how you work.

---

Use Cases

1. Multi-Tool Development

Scenario: You build agents for both Claude Desktop and Cursor IDE.

Before UACS:

.cursorrules          (Cursor config)
SKILLS.md             (Claude config)
.clinerules           (Cline config)
# Manual sync, 3x maintenance

With UACS:

# Write once in SKILLS.md
uacs skills convert --to cursorrules  # Auto-generate .cursorrules
uacs skills convert --to clinerules   # Auto-generate .clinerules
# One source, zero sync errors

2. Token Cost Optimization

Scenario: Your agent uses 10,000 tokens per call at $0.01/1K tokens.

Before UACS:

• Cost per call: $0.10
• 100 calls/day: $10/day = $300/month

With UACS (v0.1.0):

context = uacs.get_compressed_context(max_tokens=8500)  # Smart retrieval + deduplication
# 15% deduplication savings + perfect recall
# Cost per call: $0.085
# 100 calls/day: $8.50/day = $255/month
# Savings: $45/month (15%)
# Plus: 2 hours/week saved (no re-explaining after context resets)

3. Package Management

Scenario: You need testing capabilities for your agent.

Before UACS:

# Search GitHub manually
# Clone repos
# Copy-paste configs
# Update manually when changes occur

With UACS:

uacs packages install anthropic/skills-testing
# Installed in .agent/skills/ with metadata tracking
# Works with GitHub repos, Git URLs, or local paths

4. Persistent Agent Memory

Scenario: Your agent should remember project conventions across sessions.

With UACS:

# Session 1: Agent learns convention
uacs.memory.add("Use pytest-asyncio for async tests", scope="project")

# Session 2: Different agent, same project
relevant = uacs.memory.search("testing")
# Returns: "Use pytest-asyncio for async tests"
# Zero manual context management

---

What Makes UACS Different

UACS 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.

---

Quick Start

Basic Usage (v0.3.0 Semantic API)

from uacs import UACS
from pathlib import Path

# Initialize
uacs = UACS(project_path=Path("."))

# Track conversation
user_msg = uacs.add_user_message(
    content="Help me implement JWT authentication",
    turn=1,
    session_id="session_001",
    topics=["security", "feature"]
)

assistant_msg = uacs.add_assistant_message(
    content="I'll help you implement JWT. First, let's...",
    turn=1,
    session_id="session_001",
    tokens_in=42,
    tokens_out=156
)

# Capture decisions
decision = uacs.add_decision(
    question="Which auth method should we use?",
    decision="JWT tokens",
    rationale="Stateless, scalable, works with microservices",
    session_id="session_001",
    alternatives=["Session-based (doesn't scale)", "OAuth2 (overkill)"]
)

# Search semantically
results = uacs.search("how did we implement authentication?", limit=10)
for result in results:
    print(f"[{result.metadata['type']}] {result.text[:100]}...")
    print(f"Relevance: {result.similarity:.2f}\n")

See also: Full Quickstart Guide | API Reference | Examples

---

Three Ways to Use UACS

1. Python Library

from uacs import UACS
from pathlib import Path

# Initialize
uacs = UACS(project_path=Path.cwd())

# Install packages
uacs.packages.install("anthropic/skills-testing")  # From GitHub
uacs.packages.install("/path/to/local/skill")      # From local path

# Get compressed context
context = uacs.get_compressed_context(
    topic="testing",
    max_tokens=4000  # Smart deduplication + topic filtering
)

# Memory management
uacs.memory.add("Important: Always use pytest-asyncio for async tests")
relevant = uacs.memory.search("async testing")

2. CLI Tool

# Package management
uacs packages install anthropic/skills-testing
uacs packages list
uacs packages remove pytest-skill

# Format conversion
uacs skills convert --from cursorrules --to skills

# Context management
uacs context stats
uacs context compress --max-tokens 4000

# Memory
uacs memory add "Important insight"
uacs memory search "relevant topic"