gora

GoRa - A self-hosted AI companion with long-term memory, knowledge graphs, and emotional awareness

GoRa (Go based Retrieval Augmented Generation) is a self-hosted AI system that goes beyond simple document Q&A. It combines Ollama for local LLM inference, Redis for vector search, and Neo4j for structured knowledge graphs - and can operate in two modes:

• Documentation mode: Chat with your local docs. Shared vector store, factual answers, no hallucinations.
• Companion mode: A persistent AI companion that remembers you across sessions, builds a knowledge graph about your life, tracks emotional context, adapts its personality over time, and reaches out when you've been away.

Architecture

GoRa uses a hybrid retrieval strategy combining three complementary memory systems:

• Vector Search (Redis): Semantic similarity search over document embeddings for context-aware retrieval.
• Knowledge Graph (Neo4j): Structured facts and relationships extracted from documents and conversations - with confidence scoring, conflict detection, and hard-fact protection.
• Rolling Memory: Session summaries that compress long conversations into concise context, preventing token overflow. Episodic memories are archived to Neo4j for long-term recall.

Requirements

To run GoRa, you need the following components:

• Go (1.25.3 or higher)
• Docker & Docker Compose (for Redis Stack & Neo4j)
• Ollama with the following models (models can be changed in config.yml):
  • mxbai-embed-large: For high-performance embeddings.
  • mistral-nemo: For synthetic question generation, knowledge extraction, summarization, and safety classification.
  • gpt-oss:20b: For generating precise, context-aware answers.
  • qwen2.5:14b: Used for knowledge graph extraction.

Getting Started

We provide a Makefile to simplify all common tasks.

1. Spin up the infrastructure

Start Redis Stack and Neo4j:

make up

• Redis Insight: http://localhost:8001
• Neo4j Browser: http://localhost:7474

2. Prepare your data

Place your documentation (Markdown or Text files) into the /data directory. The system will automatically parse, chunk, and generate synthetic questions for these files to improve search accuracy.

3. Populate the databases

Convert your text into vectors and extract knowledge graphs:

make import

You can also import a specific file or directory:

go run ./cmd/database/import.go -path /path/to/file_or_dir

4. Start the conversation

Option A: Interactive CLI

make run

Option B: HTTP Server with Web UI

make http

Then open http://localhost:8080 in your browser.

Configuration

GoRa uses a config.yml file for all settings. If an env.yml file exists, it takes priority (useful for local overrides - env.yml is gitignored).

General Settings

Logging

Environment variable overrides: GORA_LOG_FORMAT, GORA_LOG_LEVEL, GORA_LOG_PATH.

When log_path is not set or empty, each binary writes to its own default file:

• gora (CLI): ./logs/cli.log
• gora-server (HTTP): ./logs/http.log
• gora-import (Import): ./logs/import.log

Log files are automatically rotated: max 10 MB per file, 5 backups retained, 30 days max age, gzip-compressed.

Database - Redis (Vector Store)

Database - Neo4j (Knowledge Graph)

Setup (Document Import)

Summarizer (Rolling Memory)

Safety

HTTP Server

AI - Main LLM

AI - Persona

AI - Prompts

AI - Season Context

AI - Graph

Features

Asymmetric Model Strategy

GoRa allows you to use different models for different tasks to optimize performance:

• Final Generation: Use a large model (e.g., gpt-oss:20b) for high-quality reasoning.
• Knowledge Extraction / Synthetic Questions / Summarization: Use medium/fast models (e.g., mistral-nemo, qwen2.5:14b) for speed.
• Embeddings: Specialized models like mxbai-embed-large for state-of-the-art retrieval.

Parallel Ingestion

The synthetic_question_worker_count setting controls how many document chunks are processed simultaneously.

Tip: If you have a high-end GPU with plenty of VRAM (48GB+), increase this value and set OLLAMA_NUM_PARALLEL in your environment to match for true hardware parallelism.

Index Management

By setting append_model_name_to_index: true, GoRa automatically separates your data when you switch embedding models. Since embeddings from different models are not compatible, this prevents polluting your search results.

Prompt Customization

GoRa ships with multiple prompt templates in the /prompts directory:

Switch the active prompt by changing ai.prompts.system_path in your config.

Makefile Commands

Infrastructure

Application

Testing

Database Management

Ollama

Backup & Restore

API Endpoints

Core (always available)

Companion Mode (active_learning: true)

These endpoints are only available when companion mode is enabled.

Conversation

Memory Management

Consent & Preferences

Data Management

Administration

Request Body (/api/chat and /api/chat/stream)

{
  "message": "How does GoRa handle embeddings?",
  "session_id": "my-session-id",
  "image": "<base64-encoded image data (optional)>",
  "mime_type": "image/png (required when image is set)"
}

Request Body (/api/admin/users)

{
  "name": "Alice",
  "email": "alice@example.com"
}

Health Check Response (/health)

{
  "status": "ok",
  "redis": "ok",
  "neo4j": "ok",
  "ollama": "ok"
}

Returns 200 OK when all services are healthy, 503 Service Unavailable when degraded.

Security

API Authentication

GoRa supports two authentication modes depending on the operating mode:

Documentation mode (active_learning: false): Optional shared API key via the GORA_API_KEY environment variable. If no key is configured, the API is accessible without authentication - this is acceptable for local development but should never be used in a publicly reachable environment.

Companion mode (active_learning: true): Per-user API key authentication. Each user receives a unique API key when created via make create-user or the /api/admin/users endpoint. The first user must be created via CLI.

Setting up shared API key (documentation mode)

Generate a cryptographically secure key and export it:

export GORA_API_KEY="$(openssl rand -hex 32)"

Then start the server as usual:

make http

You can create a .env file, too, add the GORA_API_KEY=1234567890abcdef and run it like

source .env && make http

All API requests must include the key as a Bearer token in the Authorization header:

curl -X POST http://localhost:8080/api/chat \
 -H "Authorization: Bearer <your-key>" \
 -H "Content-Type: application/json" \
 -d '{"message": "What is GoRa?", "session_id": "my-session"}'

Requests without a valid key will receive a 401 Unauthorized response. If you are running GoRa behind a reverse proxy (e.g. nginx or Traefik), configure http.trusted_proxies with your proxy IPs so that rate limiting operates on the real client IP rather than the proxy address.

Security Headers

GoRa sets the following security headers on all responses:

• Content-Security-Policy
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Referrer-Policy

CORS

CORS is configured globally via http.cors_allowed_origins. Defaults to ["*"] - restrict this in production.

Environment Variables

License

This project is licensed under the MIT License.