Fixies & Agents

Fixies are persistent AI assistants on the network. They are graph-aware, memory-backed, and operate across app and API layers with tier-gated capabilities.

Agent Types

Network Agents (Shared)

Three network-level agents serve all members. Each member gets an isolated conversation thread via the Letta Conversations API, so messages never mix between members.

Network agents:

• Are seeded via POST /api/fixie/seed (admin, idempotent)
• Share a shared:network Graphiti group -- facts learned in any conversation are available to all
• Use per-user conversation isolation (isolated_block_labels: ["human", "context"])
• Run at standard tier (Claude Sonnet) with full tool access

Personal Agents (Per-Member)

Every member gets a default personal Fixie on signup via bootstrapUser. Members can create up to 3 agents total through the ADE interface.

Personal agents:

• Are isolated by fixie:member:{memberId} Graphiti group
• Have their context block populated from the knowledge graph at creation
• Tier determines model, tools, and memory blocks (see Tiers below)

Creating a Fixie

Members create agents through the ADE interface at /fixies. The creation dialog offers:

1. Name -- choose a name for the agent
2. Persona type -- personal, market_analysis, query_builder, risk_assessment, or custom
3. Custom system prompt -- available when persona type is custom

Agents are created via POST /api/fixie with membership proof validation.

Tiers

Tier determines the LLM model, memory blocks, and whether sleep-time compute is enabled. All 16 tools are available to all tiers -- differentiation is model quality, not capability gating.

See Tool Access by Tier for the complete list of tools.

Knowledge Architecture

Each agent has access to three layers of knowledge. The depth of access depends on tier.

1. Letta Archives (Static, Shared)

Chunked documents (brand codex, tokenomics, compliance rules, Cypher patterns) stored as searchable passages. Attached to agents at creation time.

• fxyz-network and fxyz-compliance are attached to all agents
• fxyz-market is attached to market_analysis agents
• fxyz-graph is attached to query_builder agents
• Searched via archival_memory_search (all tiers)

2. Graphiti (Temporal, Conversational)

Facts learned from conversations are extracted into the Graphiti temporal knowledge graph via the zepai/knowledge-graph-mcp MCP server (using FalkorDB internally, not the fxyz Neo4j instance). Entities get deduplication, temporal validity edges, and group-based isolation.

• All agents can search (search_facts, search_nodes) and write (add_episode)
• Network agents share shared:network group
• Member agents use fixie:member:{memberId} group

3. Agent Memory (Per-Agent, In-Context)

Memory blocks are always in the LLM context window -- no tool call needed.

• persona -- agent identity, domain expertise, tool guidance, behavioral rules
• human -- member DID, owner ID, memory group
• context -- member's graph neighborhood (contribution level, circles, roles, wallet)
• preferences -- learned interaction patterns (premium only)

See Knowledge Architecture for the full technical reference.

System Prompt Structure

Every agent persona follows a five-section template:

1. Identity -- who the agent is, its domain, heritage
2. Knowledge Sources -- what archives are attached, what tools are available
3. Tool Priority -- ordered list of which tool to use first for different questions
4. Memory Guidance -- how to use context/preferences blocks, when to persist facts
5. Rules -- PII prohibition, MiCA terminology, communication style

Network agents have distinctive personas (Florin references the historic gold coin, Cypher references the query language, Sentinel references the watchful guardian). Member agents use configurable templates scaled by tier.

Conversation Isolation

Network agents are shared resources -- a single Letta agent serves all members. Conversation isolation prevents message mixing:

1. Member sends first message to a network agent
2. getOrCreateConversation() creates a Letta conversation with isolated_block_labels: ["human", "context"]
3. The conversation is tagged with [member:{userId}] in its summary for filtering
4. Subsequent messages use the stored conversationId
5. Each member sees only their own conversation history

Personal agents do not need this -- each member has their own agent instance.

Surfaces

All surfaces share the same backend (Letta agents, tools, archives, Graphiti). The model, memory, and knowledge layers are identical regardless of which surface a member uses.

Telegram Integration

Fixie agents are accessible directly from Telegram through two complementary interfaces: a bot for quick command-line interactions and a mini app for a full mobile chat experience.

Telegram Bot

The bot provides a lightweight command interface. Messages are sent to /api/telegram/webhook, which routes them to Letta agents via the REST API (non-streaming).

Commands:

After selecting an agent, all text messages are forwarded to that agent via Letta. If no agent is selected, the default network agent (Florin) is used.

Webhook setup: Register the webhook via POST /api/telegram/setup (admin). This calls the Telegram Bot API to point the bot at your deployment's webhook URL. Verification uses X-Telegram-Bot-Api-Secret-Token.

Telegram Mini App

The mini app is a full mobile UI served at /telegram-app inside Telegram's WebView. It uses the same useChat hook and DefaultChatTransport as the sidebar panel, providing streaming responses identical to the in-app experience.

Three-tab layout:

Platform integration:

• Uses Telegram WebApp SDK (telegram-web-app.js) for native look and feel
• Respects Telegram's color scheme (light/dark mode)
• Haptic feedback on interactions (tab switches, agent selection, message send)
• Safe area insets for bottom navigation
• noindex, nofollow meta to prevent search engine indexing

User Mapping

Telegram users are mapped to the network via Neo4j TelegramUser nodes:

• POST /api/telegram/user -- create or update a Telegram user, optionally link to a Fixie agent
• GET /api/telegram/user?telegramId=... -- look up user info and linked agents
• DELETE /api/telegram/user?telegramId=...&agentId=... -- unlink an agent

The graph relationship is (TelegramUser)-[:OWNS_FIXIE]->(FixieAgent). The bot uses an in-memory mapping during a session; persistent mapping is stored in Neo4j.

Shared Backend

Both Telegram surfaces connect to the same Letta backend as the sidebar and ADE:

• Bot path: Telegram -> /api/telegram/webhook -> Letta REST API (POST /v1/agents/{id}/messages) -> response sent back via Telegram Bot API
• Mini App path: Telegram WebView -> /telegram-app -> useChat + DefaultChatTransport -> /api/fixie/{agentId}/stream (SSE) -> Letta

All 16 custom tools, Letta Archives, Graphiti knowledge, and conversation isolation work identically on all surfaces.

API Reference

Chat (Streaming)

POST /api/fixie/{agentId}/stream
Content-Type: application/json

{ "message": "What is my current Florin balance?" }

Returns Server-Sent Events with streaming response.

Chat History

GET /api/fixie/{agentId}/chat?limit=30

Loads conversation history from Letta.

Agent Memory

GET /api/fixie/{agentId}/memory

Returns the agent's current memory blocks (persona, human, context, preferences).

Agent Tags

Agents are organized via Letta tags for efficient filtering:

Related Documentation

• Knowledge Architecture -- Three-layer knowledge system technical reference
• The Fixies -- Architecture overview
• Cypher Query Examples -- What the neo4j_query tool can do