Create characters and lorebooks from URLs using LLMs.
Lorebook Workflow
A video demonstrating the main workflow of creating a lorebook from a URL
lorebook-main-workflow-2x.mp4
Character Workflow
A video demonstrating the main workflow of creating a character from a URL
character-main-workflow-1x.mp4
[Lorebook]Manage Sources
[Lorebook]Confirming Links
[Lorebook]Generate Entries
[Lorebook]Completed Lorebook
The final generated lorebook, structured and ready for use.
[Character]Overview
[Character]Regenerate
Project Analytics
API Request Logs
- Lorebook creation: This is not deep research; it doesn't involve a web search. You need to give a URL that has multiple links. Fandom:category pages are perfect for the app. For example, you can give Oblivion Skill Books. So this is going to extract all books and navigate one by one, and create a lorebook for each book.
- Character creation: You can simply give a URL for a character. It will extract the the page.
- You can see all API request logs on the API Requests modal. You can also see the project analytics on the Project Analytics modal.
- You can edit all prompts on the Global Templates page and Project Edit modal.
- Search Params: Single LLM request. This is a very simple operation. Input token is very low.
- Manage Sources & Crawl Discover & Scan button makes one LLM request per source. If
Max Crawl Depthis more than 1, it will discover sub-categories and make an LLM request for each one. We give the LLM cleaned html, so token usage can be high. You can use Rescan Selected to find new links on previously scanned sources without using the LLM. - Generate Entries: Request count = link count. We are giving the LLM cleaned html -> markdown. Token usage depends on the page length. This step typically consumes the most tokens.
- It is only generate and regenate actions. However there are estimated token count for each source.
Choose the option that best fits your needs.
1. Create a directory and .env file
First, create a folder on your computer for the application's data. Inside that folder, create a file named .env and add a secret key phrase.
# .env file
# A secret key phrase for encrypting credentials. Can be any string, like a strong password.
# THIS KEY IS CRITICAL. IF YOU LOSE IT, ALL STORED CREDENTIALS WILL BE UNUSABLE.
APP_SECRET_KEY=yoursecretphrasehere
# The port the application will run on.
PORT=3000
# (Optional) For first-time setup, the app can create default credentials from these.
OPENROUTER_API_KEY=
GOOGLE_GEMINI_KEY=
OPENAI_COMPATIBLE_BASE_URL=
OPENAI_COMPATIBLE_API_KEY=2. Run the application Open your terminal in that same folder and choose one of the commands below.
-
To run with SQLite (Simple & Recommended): A
datafolder will be created in your current directory to store the database.-
For Linux, macOS, or WSL:
docker run -d --name lorebook-app --restart unless-stopped -p 3000:3000 \ --env-file .env \ -e APP_ENV=production \ -e DATABASE_TYPE=sqlite \ -e DATABASE_URL=/app/server/data/lorecard.db \ -v "$(pwd)/data:/app/server/data" \ ghcr.io/bmen25124/lorecard:v2.5 -
For Windows (Command Prompt):
docker run -d --name lorebook-app --restart unless-stopped -p 3000:3000 ^ --env-file .env ^ -e APP_ENV=production ^ -e DATABASE_TYPE=sqlite ^ -e DATABASE_URL=/app/server/data/lorecard.db ^ -v "%cd%/data:/app/server/data" ^ ghcr.io/bmen25124/lorecard:v2.5
-
For Windows (PowerShell):
docker run -d --name lorebook-app --restart unless-stopped -p 3000:3000 ` --env-file .env ` -e APP_ENV=production ` -e DATABASE_TYPE=sqlite ` -e DATABASE_URL=/app/server/data/lorecard.db ` -v "${pwd}/data:/app/server/data" ` ghcr.io/bmen25124/lorecard:v2.5
-
-
To run with PostgreSQL (Advanced): This requires starting a separate database container first. These commands work on all platforms.
# 1. Create a network docker network create lorebook-net # 2. Start the database container docker run -d --name lorebook-db --restart unless-stopped --network lorebook-net \ -e POSTGRES_USER=user -e POSTGRES_PASSWORD=password -e POSTGRES_DB=lorecard \ -v lorecard_postgres_data:/var/lib/postgresql/data \ postgres:13 # 3. Start the application container docker run -d --name lorebook-app --restart unless-stopped --network lorebook-net -p 3000:3000 \ --env-file .env \ -e APP_ENV=production \ -e DATABASE_TYPE=postgres \ -e DATABASE_URL=postgresql://user:password@lorebook-db:5432/lorecard \ ghcr.io/bmen25124/lorecard:v2.5
Use this method if you are on Windows and prefer not to use Docker. This script automates the entire setup process.
Prerequisites: You must have the following software installed and available in your PATH:
- Git
- Python (version 3.10 or higher)
- Node.js (version 18 or higher)
- uv (run
pip install uv) - pnpm (run
npm install -g pnpm)
1. Clone the repository
git clone https://github.com/bmen25124/lorecard.git
cd lorecard2. Run the script
Simply double-click the start.bat file or run it from your terminal:
.\start.batThe first time you run it, the script will guide you through setting up your configuration (.env file), installing all dependencies, build the client, and start the server.
Use this method if you have cloned the source code and want to build and run the application in a containerized environment. This is ideal for development.
1. Clone the repository
git clone https://github.com/bmen25124/lorecard.git
cd lorecard2. Configure your API Key Copy the example environment file.
# On Linux, macOS, or WSL
cp .env.example .env
# On Windows
copy .env.example .envNow, open the new .env file and add your API keys. Don't forget to add APP_SECRET_KEY as well.
3. Build and run the application
-
To run with SQLite (Default):
docker-compose up --build
-
To run with PostgreSQL (Optional):
docker-compose -f docker-compose.yml -f docker-compose.postgres.yml up --build
Once running, the application will be available at: http://127.0.0.1:3000/