Norns Agent

Core AI agent backend providing agentic capabilities with long-term memory.

---

Overview

Norns Agent is a Python/FastAPI service that implements the core agent logic, including the Raven Model memory system.

Property	Value
Container	norns-agent
URL	norns-pm.ravenhelm.dev
Port	8000 (internal: 3901)
Config	~/ravenhelm/docs/AI-ML-Platform/norns-agent/
Source	~/ravenhelm/docs/AI-ML-Platform/norns-agent/agent/

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     NORNS AGENT                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │   Huginn     │───▶│   Context    │───▶│   Muninn     │  │
│  │ (State/Redis)│    │  (Identity)  │    │  (Memory)    │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│         │                   │                   │          │
│         └───────────────────┼───────────────────┘          │
│                             ▼                              │
│                    ┌──────────────┐                        │
│                    │  LangGraph   │                        │
│                    │    Agent     │                        │
│                    └──────────────┘                        │
│                             │                              │
│         ┌───────────────────┼───────────────────┐          │
│         ▼                   ▼                   ▼          │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │    Tools     │    │    Claude    │    │   Langfuse   │  │
│  │ (HA, Cal...) │    │     API      │    │   (Trace)    │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
└─────────────────────────────────────────────────────────────┘

See Norns Memory System for detailed memory architecture.

---

Capabilities

Tool	Description
task_manager	CRUD operations on tasks
project_manager	Project management
calendar	Google Calendar integration
home_assistant	Smart home control
grocy	Inventory management
observability	Query Grafana/Loki/Prometheus
slack	Post messages to Slack
memory	Recall and search past interactions

---

Memory System

The agent implements the Raven Model - a three-plane cognitive architecture:

Plane	Name	Purpose
State	Huginn	Real-time session state (Redis)
Identity	Context	User identity and permissions
Memory	Muninn	Long-term episodic and semantic memory

Key Features:

• Vector embeddings via Ollama (nomic-embed-text)
• Semantic search across past interactions
• Automatic pattern extraction and learning
• Knowledge entity graph

See Norns Memory System for complete documentation.

---

API Endpoints

Endpoint	Method	Description
/health	GET	Health check
/api/chat	POST	Send chat message
/api/tasks	GET/POST	Task management
/api/projects	GET/POST	Project management
/api/memory/recall	POST	Search memories
/slack/events	POST	Slack event webhook

---

Quick Commands

# View logs
docker logs -f norns-agent

# Restart
docker restart norns-agent

# Shell access
docker exec -it norns-agent bash

# Test health
curl https://norns-pm.ravenhelm.dev/health

# Check memory stats
docker exec -i postgres psql -U ravenhelm -d ravenmaskos -c \
  "SELECT COUNT(*) as memories FROM episodic_memories;"

---

Configuration

Environment Variables

environment:
  # Database
  - DB_HOST=postgres
  - DB_PORT=5432
  - DB_NAME=ravenmaskos
  - DB_USER=ravenhelm
  - DB_PASSWORD=${POSTGRES_PASSWORD}
  
  # Redis
  - REDIS_HOST=redis
  - REDIS_PORT=6379
  - REDIS_PASSWORD=${REDIS_PASSWORD}
  
  # LLM Providers
  - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
  - OPENAI_API_KEY=${OPENAI_API_KEY}
  - OLLAMA_URL=http://ollama:11434
  
  # Embeddings
  - EMBEDDING_PROVIDER=auto
  - OLLAMA_EMBED_MODEL=nomic-embed-text
  
  # Langfuse
  - LANGFUSE_HOST=http://langfuse-web:3000
  - LANGFUSE_PUBLIC_KEY=${LANGFUSE_PUBLIC_KEY}
  - LANGFUSE_SECRET_KEY=${LANGFUSE_SECRET_KEY}
  
  # Integrations
  - SLACK_BOT_TOKEN=${SLACK_BOT_TOKEN}
  - HOMEASSISTANT_URL=http://homeassistant:8123
  - HOMEASSISTANT_TOKEN=${HOMEASSISTANT_TOKEN}

---

Slack Integration

Norns responds to messages in Slack via "The Norns" bot:

1. User mentions @The Norns in Slack
2. Slack sends event to /slack/events
3. Agent processes request with full context
4. Memory is recorded for future recall
5. Response posted back to thread

---

Troubleshooting

Issue: Agent Not Responding

Symptoms: No response to chat or Slack messages

Diagnosis:

docker logs norns-agent | tail -50
curl https://norns-pm.ravenhelm.dev/health

Solutions:

1. Check API keys are valid
2. Verify database connectivity
3. Check Langfuse is reachable

Issue: Tool Execution Failed

Symptoms: Agent responds but tool fails

Diagnosis:

# Check Langfuse for trace details
docker logs norns-agent 2>&1 | grep -A 10 "Error"

Solutions:

1. Verify integration credentials
2. Check target service is running
3. Review Langfuse traces for details

Issue: Memory Not Working

See Norns Memory System Troubleshooting