Skip to main content

​
Prerequisites

  • Python 3.12+
  • Docker & Docker Compose
  • An LLM API key (OpenAI recommended for quickstart)

​
Installation

git clone https://github.com/saxenauts/persona.git
cd persona

​
Configure Environment Variables

Copy the example environment file: 
cp .env.example .env
Edit .env with your API key: 
# LLM Services
LLM_SERVICE=openai/gpt-5.2
EMBEDDING_SERVICE=openai/text-embedding-3-small
OPENAI_API_KEY=sk-your-key-here

# Neo4j Database
# Use bolt://neo4j:7687 for Docker (default)
# Use bolt://localhost:7687 if running server locally
URI_NEO4J=bolt://neo4j:7687
USER_NEO4J=neo4j
PASSWORD_NEO4J=password
See .env.example for the full list of supported providers (OpenAI, Azure, Foundry, Anthropic, Gemini).

​
Run the Docker Containers

docker compose up -d
This starts:
  • Neo4j graph database on localhost:7474 (browser) and localhost:7687 (bolt)
  • Persona API on localhost:8000
Explore the API at http://localhost:8000/docs.

​
Interact with the API

​
Create a New User

curl -X POST http://localhost:8000/api/v1/users/alice

​
Ingest User Data

curl -X POST http://localhost:8000/api/v1/users/alice/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Had a great meeting with Sarah about the Q4 roadmap. I prefer morning meetings and want to finish the project by Friday.",
    "source_type": "conversation"
  }'

​
Perform a RAG Query

curl -X POST http://localhost:8000/api/v1/users/alice/rag/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What are my current priorities?"}'

​
Local Development (without Docker)

For development, you can run the API locally with Poetry: 
# Install dependencies
poetry install

# Start Neo4j in Docker only
docker compose up -d neo4j

# Update .env to use localhost
# URI_NEO4J=bolt://localhost:7687

# Run the API
poetry run uvicorn server.main:app --reload

​
Next Steps

Memory Model

Understand Episode, Psyche, and Goal

LLM Providers

Configure Azure, Foundry, Anthropic, and more