luna-agent: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

Luna Agent — a minimal AI assistant with persistent memory, MCP tool use, and Discord/CLI interface. It runs on Fabio's homelab (dual RTX 3090s) using a local Qwen3.5-35B-A3B model via llama-server as the LLM backend.

Commands

# Activate venv (required for all commands)
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

# Run the agent (needs DISCORD_TOKEN env var for Discord, otherwise interactive CLI)
python -m luna

# Run all tests
pytest

# Run a single test file or test
pytest tests/test_memory.py
pytest tests/test_agent.py::TestAgent::test_basic_response

# Systemd services (the agent depends on the LLM server)
sudo systemctl start worker-agent    # starts llama-server on port 8001 (Qwen3.5-35B-A3B)
sudo systemctl start luna-agent      # starts the bot (requires worker-agent)
journalctl -u luna-agent -f          # live logs

Architecture

The agent follows a straightforward pipeline: Discord message (or CLI input) → Agent loop → LLM (with tool calls) → Response.

agent.py — The orchestrator. Agent.process() is the main entry point: it saves the user message to memory, retrieves relevant memories via hybrid search, builds a system prompt with memory context, calls the LLM, executes any tool calls in a loop (max 25 rounds), saves the response, and periodically triggers summarization/fact extraction. Accepts an optional tool_callback for real-time tool call observation (used by CLI REPL).

memory.py — Persistent memory using SQLite with three search mechanisms:

• FTS5 for keyword search
• sqlite-vec for vector similarity search (embeddings from nomic-embed-text-v1.5, 384 dims)
• Reciprocal Rank Fusion (RRF) to merge both result sets, plus recency decay and importance weighting

Three tables: memories (long-term facts), messages (conversation history per session), summaries (periodic LLM-generated conversation summaries). The embedding model is lazy-loaded on first search to avoid slow startup.