Universal Agent Context

Universal Agent Context System (UACS)

Version 0.3.0 - Semantic Conversations & Knowledge Extraction

[](https://pypi.org/project/universal-agent-context/) []() []() []()

> 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](docs/MIGRATION.md) 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](docs/guides/MCPSERVERBINARY.md) | Standalone usage, no Python environment needed | None | | [Docker](docs/guides/MCPSERVERDOCKER.md) | 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](.claude-plugin/HOOKSGUIDE.md) | [Migration Guide](docs/MIGRATION.md) | [API Reference](docs/APIREFERENCE.md)

---

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](docs/CLI_REFERENCE.md) | [Examples](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](uacs-web-ui/README.md) | [Implementation Complete](./.github/NEXTJSWEBUICOMPLETE.md)

---

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](QUICKSTART.md) | [API Reference](docs/API_REFERENCE.md) | [Examples](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"

3. MCP Server (For Claude Desktop, Cursor, Windsurf)

# Start MCP server
uacs serve

# Or with uvx (one-liner)
uvx universal-agent-context serve

Configure in Claude Desktop:

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "uacs": {
      "command": "uacs",
      "args": ["serve"],
      "env": {
        "UACS_PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}

Now Claude Desktop can:

• Manage packages from GitHub, Git, or local paths
• Convert between formats on-the-fly
• Compress large contexts automatically
• Access your project memory
• Install skills directly from conversation

---

Core Features

🔄 Format Translation

The Problem: You write for Claude (SKILLS.md), but also need Cursor (.cursorrules) and Cline (.clinerules) configs.

The Solution: Write once, deploy everywhere.

# Convert .cursorrules to SKILLS.md
uv run uacs skills convert --from cursorrules --to skills

# Or in Python:
from uacs.adapters import FormatAdapterRegistry

adapter = FormatAdapterRegistry.get_adapter("cursorrules")
content = adapter.parse(Path(".cursorrules").read_text())
skills_format = content.to_system_prompt()

Supported Formats:

• ✅ Agent Skills (SKILLS.md) - Anthropic standard (spec)
• ✅ AGENTS.md - Project context standard (spec)
• ✅ .cursorrules - Cursor IDE format
• ✅ .clinerules - Cline VSCode extension
• 🚧 ADK Agent Config - Google ADK format (Coming Phase 7)

Quality validation included: All conversions verify structure, check for required fields, score quality.

🗜️ Context Compression

The Problem: Large contexts = high costs. A 10K token call costs $0.10. At scale, this adds up fast.

The Solution: Smart context management with perfect recall.

Current Implementation (v0.1.0):

1. Deduplication - Hash-based, automatic (15% savings)
2. Quality Filtering - Remove noise, keep signal
3. Topic-Based Retrieval - Focus on relevant context
4. Exact Storage - 100% fidelity, zero information loss

Coming in v0.2.0:

1. LLM Summarization - Claude Haiku for intelligent compression
2. Vector Embeddings - Semantic similarity search
3. Knowledge Graph - Context relationship traversal
4. Target: 70%+ compression with zero information loss

Real-world Impact (v0.1.0):

# Deduplication savings:
- Original context: 10,000 tokens
- After deduplication: 8,500 tokens (15% savings)
- Cost per call: $0.085 (vs $0.10)
- 100 calls/day: $8.50/day vs $10/day
- Monthly savings: $45 (15%)

# Plus time savings:
- Context never lost = no re-explaining
- Save ~2 hours/week for active developers

Usage:

# Automatic compression
context = uacs.get_compressed_context(
    topic="security review",  # Filter by topic
    max_tokens=4000,          # Target size
    agent="claude"            # Filter by agent (optional)
)

# Check what you saved
stats = uacs.get_token_stats()
print(f"Saved: {stats['tokens_saved_by_compression']} tokens")
print(f"Ratio: {stats['compression_ratio']}")

📦 Package Management

The Problem: Skills scattered across GitHub. MCP servers in different repositories. Manual cloning and installation.

The Solution: Simple package manager modeled after GitHub CLI extensions.

# Install from GitHub
uv run uacs packages install anthropic/skills-testing

# Install from Git URL
uv run uacs packages install https://github.com/owner/repo.git

# Install from local path
uv run uacs packages install /path/to/skill

# List installed packages
uv run uacs packages list

# Update packages
uv run uacs packages update

Installation sources:

• ✅ GitHub repositories (owner/repo)
• ✅ Git URLs (HTTPS or SSH)
• ✅ Local paths (absolute or relative)

Installation tracking:

# Install package
uv run uacs packages install anthropic/skills-testing

# Stored in: .agent/skills/testing/
# Metadata: .agent/skills/.installed.json (tracks source, version, installed date)

# Uninstall
uv run uacs packages remove testing

🧠 Memory & Knowled

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kylebrodeur
• Source: kylebrodeur/universal-agent-context
• License: MIT

Install and usage instructions live in the source repository linked above.