Vouchstone
Documentation/Quick Start

Quick Start Guide

Get up and running with Vouchstone in under 10 minutes. This guide will walk you through creating your first AI agent with persistent memory.

Prerequisites

Before you begin, ensure you have the following:

New Account Bonus

New accounts automatically receive 5,000 Vouchstone tokens to get started. This is enough to create several agents and run thousands of interactions.

Step 1: Install the SDK

Install the Vouchstone Python SDK:

pip install vouchstone-sdk

Step 2: Configure Authentication

Set your API key as an environment variable or pass it directly to the client. We recommend using environment variables for security.

Using Environment Variables

# Add to your .env file or shell profile
export VOUCHSTONE_API_KEY="your-api-key-here"

Python Configuration

from vouchstone_sdk import VouchstoneClient

# api_key and control_plane_url are both required -- there is no default
# control plane URL, point it at your own instance.
client = VouchstoneClient(
    api_key="your-api-key-here",
    control_plane_url="https://your-control-plane-host.example.com",
)

Keep Your API Key Secure

Never commit your API key to version control or expose it in client-side code. Always use environment variables or a secrets manager in production.

Step 3: Create Your First Agent

Now let's create an AI agent. Agents in Vouchstone are intelligent entities that can remember context, learn from interactions, and perform tasks.

Python Example

Agents are built locally by subclassing Agent and implementing run() — there is no server-side "create agent" call.

from vouchstone_sdk import Agent, AgentConfig, Message, AgentResponse, MemoryContext

class SupportAssistant(Agent):
    async def run(self, message: Message, context: MemoryContext) -> AgentResponse:
        response = await self.llm.complete(
            system=self.config.system_prompt,
            messages=[{"role": "user", "content": message.content}],
        )
        return AgentResponse(content=response)

config = AgentConfig(
    name="Support Assistant",
    model="claude-sonnet-4-20250514",
    system_prompt="You are a friendly, professional, concise support agent.",
)
agent = SupportAssistant(config)
await agent.initialize(agent_id="support-assistant-1")

Step 4: Interact with Your Agent

Once your agent is initialized, send it messages via process(). It automatically stores each turn in episodic memory for future context.

Python Example

# process() prepares memory context, calls run(), then persists the turn
response = await agent.process(Message(content="Hello! I need help with my account."))
print(response.content)

# The agent remembers the conversation via episodic memory
response = await agent.process(Message(content="I forgot my password."))
print(response.content)

# Access recent episodic history for this agent
history = await agent.pipeline.episodic.get_recent("support-assistant-1", limit=10)
for trace in history:
    print(f"user: {trace.user_input}")
    print(f"agent: {trace.agent_response}")

Step 5: Add Knowledge to Memory

Enhance your agent's capabilities by adding documents, FAQs, or other knowledge to its semantic memory.

Python Example

# Add facts to the agent's semantic memory (inside run(), self.pipeline
# is available; from outside the class, use agent.pipeline directly)
await agent.pipeline.semantic.store(
    "To reset your password, go to Settings > Security > Reset Password.",
    metadata={"category": "account", "topic": "password"},
)
await agent.pipeline.semantic.store(
    "Subscription plans: Free (5 agents), Pro ($149/mo, 100 agents), Enterprise (custom).",
    metadata={"category": "billing", "topic": "pricing"},
)

# The agent can now answer questions about these topics
response = await agent.process(Message(content="What are the pricing plans?"))
print(response.content)  # Will reference the pricing information

Step 6: Deploy and Scale

The data plane — your agent runtime, memory stores, and connectors — runs inside your own infrastructure (VPC or air-gapped), not a Vouchstone-managed host. Package your agent into the runtime image and deploy it with the provided Helm chart:

Deploy to Production

helm install my-agent-runtime ./data-plane/helm-charts/vouchstone-runtime \
  --set replicaCount=1 \
  --set image.tag=1.0.0 \
  -f my-values.yaml

See data-plane/helm-charts/vouchstone-runtime/values.yaml for the full set of configurable values (resource limits, connector credentials, memory backend URLs, and more).

Single-instance today — multi-replica HA is a future initiative

Run with replicaCount: 1 for now. The chart exposes a higher replicaCount and an HPA, but Episodic and Meta-Memory still fall back to in-process, non-shared state, Semantic and Procedural Memory fall back to embedded in-process backends until real ChromaDB/Neo4j subcharts are wired in, and the execution store is still per-pod SQLite — so a second replica can silently diverge or 404 on status polls depending on which pod answers. Don't raise replicaCount in a real deployment until a shared vector/graph DB and a shared execution store are in place.

Integration Options

Connect your agent to various platforms:

Slack Integration

Deploy your agent as a Slack bot for team collaboration.

Microsoft Teams

Integrate with Microsoft Teams for enterprise deployments.

Webhooks

Receive real-time notifications about agent activity.

REST API

Direct API access for custom integrations.

Next Steps

Congratulations! You've created your first Vouchstone agent. Here's what to explore next:

Document Vault Workflow

When you connect data sources via Connectors, all ingested data flows through the Document Vault before reaching the Knowledge Graph. The Vault provides a 3-layer moderation pipeline (Raw, Workspace, Canonical) where your team can review, edit, and approve documents before they feed into the KG, Wiki, and Company Brain. Go to Document Vault in the sidebar to review staged documents, or enable auto-pilot mode for trusted sources.
IntroductionInstallation Guide