ƒxyz Network Docs

Architecture of the Fixie AI agent layer - Letta framework, three-layer knowledge, tier system, and deployment.

Framework: Letta v0.16.6 | Agent Type: letta_v1_agent | Server: letta.fxyz.network

Fixies are the AI-assistant layer in the ƒxyz stack. They are persistent, graph-aware, memory-backed agents exposed through four surfaces: the ADE page, sidebar panel, Telegram bot, and Telegram mini app. Each agent is a Letta letta_v1_agent with structured memory blocks, tier-gated tools, and access to a three-layer knowledge system. All surfaces share the same backend -- the same tools, archives, and knowledge layers are available everywhere.

Architecture

Sidebar (Cmd+Shift+F) ──┐
ADE (/fixies) ───────────┤
TG Mini App ─────────────┼──→ /api/fixie/[agentId]/stream ──→ Letta ──→ Tools
TG Bot ──────────────────┘──→ /api/telegram/webhook ─────────→ Letta (REST, non-streaming)
                                       |
                                       v
                              Next.js API (apps/api)
                                       |
                                       | @letta-ai/letta-client SDK
                                       v
                              Letta Server (letta.fxyz.network)
                                       |
                                       +-- Agent Memory (persona, human, context, preferences)
                                       +-- Letta Archives (fxyz-network, fxyz-compliance, fxyz-market, fxyz-graph)
                                       +-- Custom Tools (Python sandboxed -> HTTP POST -> API endpoints)
                                       +-- MCP: Graphiti (zepai/knowledge-graph-mcp -> FalkorDB)
                                       |
                                       v
                              Neo4j (domain graph, queried by neo4j_query tool)
                              FalkorDB (Graphiti's internal graph store, separate from Neo4j)
                              Solana (on-chain token data)

Surface Routing

Surface	Entry Point	Transport	Streaming
Sidebar (`Cmd+Shift+F`)	`useChat` + `DefaultChatTransport`	SSE via `/api/fixie/{agentId}/stream`	Yes
ADE (`/fixies`)	`useChat` + `DefaultChatTransport`	SSE via `/api/fixie/{agentId}/stream`	Yes
Telegram Mini App	`useChat` + `DefaultChatTransport`	SSE via `/api/fixie/{agentId}/stream`	Yes
Telegram Bot	Telegram Bot API webhook	REST via `/api/telegram/webhook` -> Letta REST	No

Key Components

Component	Role	Location
Fixie Service	Agent CRUD, tier logic, persona templates, archive attachment	`apps/api/app/api/fixie/service.ts`
Tool Definitions	Python tool source code with API callbacks	`apps/api/app/api/fixie/tool-definitions.ts`
Conversation Helpers	Per-user conversation isolation on shared agents	`apps/api/app/api/fixie/conversation-helpers.ts`
Archive Routes	Archive creation and document ingestion	`apps/api/app/api/fixie/archives/`
MCP Route	Graphiti MCP server registration	`apps/api/app/api/fixie/mcp/route.ts`
Stream Route	SSE streaming chat (used by sidebar, ADE, and TG mini app)	`apps/api/app/api/fixie/[agentId]/stream/route.ts`
Member Context	Graph neighborhood builder for context blocks	`apps/api/app/api/fixie/member-context.ts`
Telegram Webhook	Bot message handler, routes to Letta REST API	`apps/api/app/api/telegram/webhook/route.ts`
Telegram Setup	Webhook registration with Telegram Bot API	`apps/api/app/api/telegram/setup/route.ts`
Telegram User	Neo4j TelegramUser node CRUD and agent linking	`apps/api/app/api/telegram/user/route.ts`
Telegram Mini App	3-tab mobile UI (chat, agent list, create)	`apps/app/app/telegram-app/`
Telegram Provider	WebApp SDK integration, haptics, theme, buttons	`apps/app/app/telegram-app/components/telegram-provider.tsx`

Agent Types

Network Agents

Three shared agents serve all members with per-user conversation isolation:

Agent	Persona Type	Domain	Graphiti Group
Florin	`market_analysis`	Market intelligence, portfolio	`shared:network`
Cypher	`query_builder`	Knowledge graph, Cypher queries	`shared:network`
Sentinel	`risk_assessment`	Risk, governance, compliance	`shared:network`

Seeded via POST /api/fixie/seed. Run at standard tier (Claude Sonnet).

Member Agents

Auto-created on signup via bootstrapUser. Members can create up to 3 agents. Persona types: personal, market_analysis, query_builder, risk_assessment, custom.

Three-Layer Knowledge System

Layer	Source	Tools	Details
Letta Archives	Ingested docs (brand, compliance, market, graph)	`archival_memory_search`	Attached at agent creation, shared across agents
Graphiti	Conversation-extracted entities and facts	`search_facts`, `search_nodes`, `add_episode`	Temporal edges, deduplication, group isolation (FalkorDB backend)
Agent Memory	Per-agent blocks (persona, human, context, preferences)	Always in-context	Populated from graph, updated during conversations

Full reference: Knowledge Architecture

Tier System

Tier differentiation is based on model quality and memory depth, not tool access. All 16 tools are available to all tiers.

	Free	Standard	Premium
Model	Claude Haiku	Claude Sonnet	Claude Opus
Memory	persona, human	+ context	+ preferences
Sleep-time	--	--	Yes
Tools	All 16 tools	All 16 tools	All 16 tools

Tier config is defined in FIXIE_TIERS in service.ts.

Surfaces

Surface	Description
`/fixies`	ADE page: 3-panel layout (agent list, chat, agent state/memory)
`Cmd+Shift+F`	Sidebar panel with streaming chat
Telegram Mini App	Mobile-native 3-tab UI (`/telegram-app`): chat, agent list, agent creation
Telegram Bot	Command-driven chat via `/api/telegram/webhook` (non-streaming)
`/api/fixie/*`	Backend route family for all agent operations
`/api/telegram/*`	Telegram webhook, user mapping, and setup routes

Knowledge Architecture -- Three-layer knowledge system
Fixies & Agents Guide -- User-facing guide with API reference
Cypher Query Examples
Graph Explorer

The Fixies