Knowledge Architecture

Three-layer knowledge system powering Fixie AI agents: Letta Archives, Graphiti temporal graph, and per-agent memory

Status (verified 2026-05-22): Graphiti is planned, not deployed. The schema (mig 015 + mig 045) lives in Neo4j ready for activation; the Graphiti MCP container has never been provisioned on prod. Letta v0.16.8 runs at LETTA_BASE_URL for non-Graphiti memory. Active forward plan: docs/architecture/TEXT2KG_GRAPHITI_INTEGRATION_2026-05-20.md (slow-and-steady 5-gate flow per founder mandate 2026-05-20). The Graphiti-specific tools (search_facts, search_nodes, add_episode, get_episodes) were detached from active Fixie agents on 2026-05-18 (commit b8e40027a) until deployment ships. Read this page as the planned architecture; the live-today subset is Letta archival memory + Neo4j read-paths.

Fixie AI agents operate on a three-layer knowledge system. Each layer serves a different purpose, update frequency, and scope. Together they give agents access to static documentation, temporal conversational facts, and personal memory -- all isolated by membership and tier.

All agent surfaces -- the ADE page (/fixies), sidebar panel (Cmd+Shift+F), Telegram mini app, and Telegram bot -- share the same knowledge layers. A fact learned during a sidebar conversation is available when the same member messages via Telegram, and vice versa. The knowledge architecture is surface-agnostic; only the transport differs.

Overview

Three Knowledge Layers

Layer	Technology	Content	Scope	Update Frequency
Network Knowledge	Letta Archives	Brand, tokenomics, compliance, architecture docs	Shared across all agents	Manual ingestion when docs change
Temporal Knowledge	Graphiti (MCP)	Facts extracted from conversations, entity relationships	Isolated by `group_id`	Automatic during conversations
Agent Memory	Letta Core Memory	Persona, human context, preferences	Per-agent instance	Updated every conversation

Three Knowledge Layers:

+------------------------------------------------------------------+
|                     LETTA SERVER (v0.16.8)                        |
|                                                                   |
|  LAYER 3: Agent Memory           LAYER 1: Letta Archives         |
|  (per-agent, in-context)         (shared, searchable)             |
|                                                                   |
|  +------------------+            +---------------------------+    |
|  | persona          |            | fxyz-network              |    |
|  | human            |            |   brand, tokenomics, arch |    |
|  | context          |            | fxyz-compliance           |    |
|  | preferences      |            |   MiCA, VASP, regs        |    |
|  +------------------+            | fxyz-market               |    |
|                                  |   FX theory, math models  |    |
|  LAYER 2: Graphiti (MCP)         | fxyz-graph                |    |
|  (temporal, conversational)      |   Cypher, schema, ontology|    |
|                                  +---------------------------+    |
|  +---------------------------+                                    |
|  | search_facts              |                                    |
|  | search_nodes              |                                    |
|  | add_episode               |                                    |
|  | get_episodes              |                                    |
|  +------------+--------------+                                    |
+---------------|---------------------------------------------------+
                | streamable_http (MCP)
                v
+------------------------------------------------------------------+
|              GRAPHITI SERVICE (zepai/knowledge-graph-mcp)         |
|                                                                   |
|  graphiti-core: entity extraction, temporal edges, deduplication  |
|  group_id isolation: shared:network | member:{id} | circle:{id}  |
|                                                                   |
|  Connects to: shared fxyz Neo4j (graphiti-node1 container)        |
|  LLM:         Claude Haiku (entity extraction)                   |
|  Embeddings:  openai/text-embedding-3-small (1536 dim)           |
+------------------------------------------------------------------+
                |
                v
+------------------------------------------------------------------+
|               SHARED fxyz NEO4J (graphiti-node1 container)        |
|                                                                   |
|  Graphiti nodes: :Entity, :EpisodicNode, :CommunityNode          |
|  Isolation: group_id property on all Graphiti nodes               |
|  NOTE: Writes into the same Neo4j as the fxyz domain graph        |
+------------------------------------------------------------------+

Layer 1: Letta Archives (Static Shared Knowledge)

Archives are collections of chunked document passages stored in Letta and attached to agents at creation time. They provide the baseline knowledge every agent needs.

Archive Definitions

Archive	Content	Attached To
`fxyz-network`	Brand codex, tokenomics v5.1, founding philosophy, architecture overview	All agents
`fxyz-compliance`	MiCA VASP requirements, regulatory frameworks, jurisdictions	All agents
`fxyz-market`	FX theory, mathematical models, market analysis patterns	`market_analysis` persona agents
`fxyz-graph`	Neo4j schema, Cypher patterns, ontology docs, knowledge graph structure	`query_builder` persona agents

How Archives Work

Archives are created via POST /api/fixie/archives (admin, idempotent)
Documents are ingested via POST /api/fixie/archives/ingest with chunking (1500 chars, 200 overlap)
Agents search archives using archival_memory_search (built-in Letta tool)
Network + compliance archives are attached to every agent at creation
Type-specific archives are attached based on personaType

Agent Access

Agents query archives with archival_memory_search({ query: "..." })
Passages are returned ranked by semantic similarity
Premium agents can also write with archival_memory_insert for personal archival storage

Layer 2: Graphiti (Temporal Conversational Knowledge)

Graphiti provides what static archives cannot: entity extraction, temporal validity, cross-referencing, and deduplication of knowledge learned from conversations.

What Graphiti Does

Capability	Description
Entity Extraction	LLM-driven extraction of entities and relationships from conversation text
Temporal Edges	Facts have `tValid` / `tInvalid` timestamps -- knowledge can expire or be superseded
Deduplication	Same entity mentioned differently across conversations gets merged (0.85 cosine threshold)
Group Isolation	`group_id` property on every node ensures tenant isolation within shared Neo4j

Deployment

Graphiti runs as a standalone container (graphiti-node1) registered with Letta as a streamable_http MCP server. Graphiti writes :Entity and :Episodic nodes into the shared fxyz Neo4j instance, not a separate FalkorDB. Graphiti labels (:Entity, :EpisodicNode, :CommunityNode) land in the same Neo4j as the domain graph, isolated by group_id.

# docker-compose.graphiti.yaml
services:
  graphiti:
    image: zepai/knowledge-graph-mcp:latest
    container_name: graphiti-node1
    hostname: graphiti-server
    environment:
      MODEL_NAME: claude-haiku-4-5     # entity extraction (cheap, fast)
      EMBEDDING_MODEL: openai/text-embedding-3-small
      EMBEDDING_DIM: "1536"
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      # Points to shared fxyz Neo4j (not a separate FalkorDB)
      NEO4J_URI: bolt://neo4j:7687
      NEO4J_USER: neo4j
      NEO4J_PASSWORD: ${NEO4J_PASSWORD}
    ports:
      - "8199:8199"

MCP registration is done via POST /api/fixie/mcp (admin, idempotent). Graphiti is registered as a streamable_http transport.

Group-Based Isolation

Group ID Pattern	Scope	Used By
`shared:network`	Network-wide facts from Florin/Cypher/Sentinel conversations	Network agents
`fixie:member:{memberId}`	Personal facts from member agent conversations	Member agents
`fixie:project:{projectId}`	Project-scoped knowledge (future)	Project agents

Graphiti Tools

Tool	Description
`search_facts`	Search temporal facts in the knowledge graph
`search_nodes`	Search entity nodes in the knowledge graph
`add_episode`	Add a conversation episode for entity extraction
`get_episodes`	Get recent episodes from the graph

All tiers have access to all Graphiti tools. Tier differentiation is based on model quality (Haiku / Sonnet / Opus), not tool access.

Neo4j Graph Isolation

Graphiti writes into the shared fxyz Neo4j instance. Graphiti's labels co-exist with the fxyz domain graph:

Graphiti Label	Purpose
`:Entity`	Extracted semantic entities (people, concepts, preferences)
`:EpisodicNode`	Raw episode/message storage
`:CommunityNode`	Entity clusters

Tenant isolation is enforced by group_id property on all Graphiti nodes within the shared Neo4j instance.

Layer 3: Agent Memory (Per-Agent Blocks)

Each Fixie agent has in-context memory blocks that are always available to the LLM without requiring a tool call.

Memory Blocks by Tier

Block	Free	Standard	Premium	Description
`persona`	Yes	Yes	Yes	Agent identity, domain, tool guidance, behavioral rules
`human`	Yes	Yes	Yes	Member context (DID, owner ID, memory group)
`context`	--	Yes	Yes	Member's graph neighborhood (contribution level, circles, roles, wallet)
`preferences`	--	--	Yes	Learned interaction patterns and preferences

The context block is populated at agent creation from the knowledge graph via buildMemberContext(), and can be refreshed via the member_status tool.

Sleep-Time Compute (Premium)

Premium agents have enable_sleeptime: true, allowing Letta to process and organize memories between conversations for improved recall quality.

Tool Access by Tier

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

Note (2026-05-18): The four Graphiti tools (graphiti_search_facts, graphiti_search_nodes, graphiti_add_episode, graphiti_get_episodes) were detached from active Fixie agents in commit b8e40027a pending full Graphiti integration. They appear in the schema definition but are not currently active on running agents.

Tool	Free	Standard	Premium	Network
`conversation_search`	Yes	Yes	Yes	Yes
`memory_replace`	Yes	Yes	Yes	Yes
`memory_insert`	Yes	Yes	Yes	Yes
`neo4j_query`	Yes	Yes	Yes	Yes
`member_status`	Yes	Yes	Yes	Yes
`solana_portfolio`	Yes	Yes	Yes	Yes
`graphiti_search_facts`	Detached	Detached	Detached	Detached
`graphiti_search_nodes`	Detached	Detached	Detached	Detached
`archival_memory_search`	Yes	Yes	Yes	Yes
`archival_memory_insert`	Yes	Yes	Yes	Yes
`graphiti_add_episode`	Detached	Detached	Detached	Detached
`graphiti_get_episodes`	Detached	Detached	Detached	Detached
`web_search`	Yes	Yes	Yes	Yes
`solana_transactions`	Yes	Yes	Yes	Yes
`governance_status`	Yes	Yes	Yes	Yes
`circle_activity`	Yes	Yes	Yes	Yes

Knowledge Flow

Information moves through the system in a cycle:

1. Documentation (markdown, MDX, research docs)
   |
   v  [POST /api/fixie/archives/ingest]
2. Letta Archives (chunked passages, searchable)
   |
   v  [archival_memory_search]
3. Agent Conversations (agent reads archives, answers member questions)
   |
   v  [add_episode]
4. Graphiti (entity extraction, temporal edges, deduplication)
   |
   v  [search_facts, search_nodes]
5. Future Conversations (agent recalls learned facts, refines answers)

Key properties of this flow:

Archives are static: updated when docs change, not during conversations
Graphiti is dynamic: grows as agents have conversations and learn facts
Agent memory is ephemeral: context and preferences blocks are per-agent, refreshed from the graph
Isolation is enforced: group_id on Graphiti nodes, archive attachment on agents, conversation isolation on network agents

References

Letta (formerly MemGPT) Framework -- AI agent memory architecture
Graphiti (Zep) -- Temporal knowledge graph
Packer, C. et al. "MemGPT: Towards LLMs as Operating Systems." arXiv:2310.08560, 2023 -- Foundational paper for Letta's memory model

Knowledge Architecture

On this page