Knowledge Graph
The Knowledge Graph (KG) is a persistent, automatically-maintained graph of entities and relationships extracted from every conversation. It provides the agent with a structured, long-term understanding of the user's world.
What Gets Extracted
After every message, extract_from_conversation() processes the conversation and identifies:
- People — names, roles, relationships to the user
- Organizations — companies, projects, teams
- Places — locations, servers, URLs
- Crypto assets — tickers, prices mentioned
- Preferences — stated user preferences and habits
- Facts — domain-specific knowledge
Extraction Rules
Extraction is rule-based (no extra LLM call needed):
# Price pattern: "BTC is at $67,000"
r"(\bBTC\b|\bETH\b|\bADA\b).*?\$[\d,.]+"
# Person pattern: "my colleague John works on DevOps"
r"(?:my\s+)?(?:colleague|friend|boss|manager)\s+(\w+)"
# Preference pattern: "I prefer dark mode"
r"I\s+(?:prefer|like|want|use)\s+(.+)"
Contamination guards prevent garbage extraction (partial sentences, error messages, etc.).
Storage Schema
knowledge_nodes Table
| Column | Type | Description |
|---|---|---|
id | UUID | Node identifier |
entity_type | string | person, org, place, asset, preference |
name | string | Entity name/label |
properties | JSONB | Flexible attributes |
chat_id | string | Scoped to conversation |
created_at | timestamp | First seen |
updated_at | timestamp | Last updated |
knowledge_relations Table
| Column | Type | Description |
|---|---|---|
id | UUID | Relation identifier |
from_node | UUID | Source node |
to_node | UUID | Target node |
relation_type | string | works_at, owns, prefers, etc. |
weight | float | Confidence (0-1) |
created_at | timestamp | When extracted |
Redis Cache
Frequently-accessed nodes are cached in Redis:
kg:node:{entity_id} → JSON blob (node + recent relations)
Cache is populated on first access and invalidated on update. This prevents repeated PostgreSQL queries for common entities.
Context Injection
The KG is injected into every system prompt:
[KNOWLEDGE GRAPH]
People: John (colleague, DevOps), Maria (friend, developer)
Assets: BTC ($67,663, -0.99% today), ETH ($1,950, -1.68% today)
Preferences: dark mode, concise responses, Python over JS
Organizations: Hostinger (VPS provider)
Only the most relevant and recent nodes are included (token budget aware).
Querying the Knowledge Graph
Via the knowledge_graph skill:
knowledge_graph(action="search", query="who is John")
knowledge_graph(action="list", type="people")
knowledge_graph(action="get", entity_id="uuid-here")
Or directly via API:
docker exec agent-postgres psql -U agent -d agent -c \
"SELECT name, entity_type, properties FROM knowledge_nodes ORDER BY updated_at DESC LIMIT 20;"
Relationship Traversal
The agent can ask for relationship chains:
knowledge_graph(action="neighbors", entity="BTC", depth=2)
Returns: BTC → price_data → last_updated, BTC → alert → threshold_70k, etc.
Privacy and Scoping
Each node is scoped to a chat_id. Data from one conversation is not visible to queries from a different chat ID. This provides basic multi-tenant isolation.
Integration with World Model
The KG feeds the World Model:
- Crypto assets in the KG are monitored by
BackgroundPerceptionJob - When prices change >4%, a proactive alert is generated
- The temporal model uses KG entities as subjects for historical tracking
Maintenance
KG nodes are never automatically deleted (they represent accumulated knowledge). To manually clean:
docker exec agent-postgres psql -U agent -d agent -c \
"DELETE FROM knowledge_nodes WHERE updated_at < NOW() - INTERVAL '90 days';"