Configuration

Kore Memory is configured entirely via environment variables. No configuration files are needed. All settings have sensible defaults that work out of the box for local development.

Environment Variables

Variable	Default	Description
KORE_DB_PATH	data/memory.db	Path to the SQLite database file
KORE_HOST	127.0.0.1	Server bind address
KORE_PORT	8765	Server port
KORE_LOCAL_ONLY	1	Skip API key auth for localhost requests
KORE_API_KEY	auto-generated	Override the API key (see Authentication)
KORE_CORS_ORIGINS	(empty)	Comma-separated list of allowed CORS origins
KORE_EMBED_MODEL	paraphrase-multilingual-MiniLM-L12-v2	Sentence-transformers model name
KORE_MAX_EMBED_CHARS	8000	Maximum characters sent to the embedding model
KORE_SIMILARITY_THRESHOLD	0.88	Cosine similarity threshold for compression
KORE_LOG_LEVEL	info	Logging level (debug, info, warning, error)

Database Path

By default, Kore creates the database at data/memory.db relative to the working directory. Override this for custom deployments:

# Use an absolute path
KORE_DB_PATH=/var/lib/kore/production.db kore

# Separate databases per environment
KORE_DB_PATH=./data/staging.db kore

info

The directory must exist. Kore will create the .db file and its WAL journal automatically, but it will not create parent directories.

Network Binding

Local Only (Default)

KORE_HOST=127.0.0.1 KORE_PORT=8765 kore

The server is only accessible from the local machine. This is the safest default.

Expose to Network

KORE_HOST=0.0.0.0 KORE_PORT=8765 KORE_LOCAL_ONLY=0 kore

warning

When binding to 0.0.0.0, always set KORE_LOCAL_ONLY=0 and ensure KORE_API_KEY is set or auto-generated. Without authentication, any machine on your network can read and write memories.

Custom Port

KORE_PORT=9000 kore

Authentication

Local Mode (Default)

When KORE_LOCAL_ONLY=1 (the default), requests from 127.0.0.1 and ::1 skip API key validation entirely. This makes local development frictionless.

API Key Authentication

For non-localhost access, Kore requires an X-Kore-Key header:

curl -H "X-Kore-Key: your-api-key" http://your-server:8765/search?q=test

The API key is handled in one of two ways:

1. Auto-generated -- On first run, Kore generates a cryptographically random key and stores it at data/.api_key with mode 600 (owner-read only). The key is printed to the console on startup.

2. Manual override -- Set KORE_API_KEY to use a specific key:

KORE_API_KEY=my-secret-key-here kore

tip

The auto-generated key is recommended for most deployments. It is unique per database directory and never transmitted over the network.

Security Features

Kore implements multiple security layers:

• Timing-safe key comparison -- Prevents timing attacks on API key validation
• Parameterized SQL -- All queries use parameters, preventing SQL injection
• Pydantic v2 validation -- All input is validated and sanitized before processing
• Per-IP and per-path rate limiting -- Prevents abuse
• Security headers -- X-Content-Type-Options, X-Frame-Options, CSP, Referrer-Policy
• FTS5 sanitization -- Special characters are stripped and token counts limited
• CSP nonce per request -- No unsafe-inline in Content Security Policy

CORS Configuration

By default, CORS is restricted (no cross-origin requests allowed). To allow specific origins:

# Single origin
KORE_CORS_ORIGINS="https://app.example.com" kore

# Multiple origins
KORE_CORS_ORIGINS="https://app.example.com,https://admin.example.com" kore

warning

Avoid setting CORS to * in production. Always specify exact origins.

Embedding Models

The default model paraphrase-multilingual-MiniLM-L12-v2 provides:

• 50+ language support
• 384-dimensional embeddings
• ~120 MB download (cached after first use)
• Fast CPU inference

Changing the Model

You can use any model from the sentence-transformers library:

# Larger, more accurate model
KORE_EMBED_MODEL=paraphrase-multilingual-mpnet-base-v2 kore

# English-only, smaller model
KORE_EMBED_MODEL=all-MiniLM-L6-v2 kore

warning

Changing the embedding model after memories have been saved will make existing embeddings incompatible with new ones. Search quality will degrade. If you change models, re-embed all memories or start with a fresh database.

OOM Protection

The KORE_MAX_EMBED_CHARS variable caps the input length to the embedding model. This prevents out-of-memory errors on machines with limited RAM:

# Default: 8000 characters
KORE_MAX_EMBED_CHARS=8000

# For memory-constrained environments
KORE_MAX_EMBED_CHARS=4000

Content exceeding this limit is truncated before embedding. The full text is still stored in the database.

Compression Threshold

The KORE_SIMILARITY_THRESHOLD variable controls how aggressively the compression engine merges similar memories:

# Default: 0.88 (conservative)
KORE_SIMILARITY_THRESHOLD=0.88

# More aggressive compression
KORE_SIMILARITY_THRESHOLD=0.80

# Very conservative (only near-duplicates)
KORE_SIMILARITY_THRESHOLD=0.95

Threshold	Behavior
0.80	Aggressive -- merges loosely similar memories
0.88	Default -- merges clearly redundant memories
0.95	Conservative -- only merges near-exact duplicates

Namespace Isolation

Kore supports multi-agent deployments via the X-Agent-Id header. Each agent operates in its own isolated namespace:

# Agent A saves a memory
curl -X POST http://localhost:8765/save \
  -H "X-Agent-Id: agent-a" \
  -d '{"content": "Secret project details"}'

# Agent B cannot see Agent A's memories
curl "http://localhost:8765/search?q=secret" \
  -H "X-Agent-Id: agent-b"
# Returns: empty results

How It Works

• Every memory is tagged with the agent ID that created it
• Search, timeline, tags, and relations are all scoped to the requesting agent
• The default agent ID is "default" when no header is provided
• There is no cross-agent API -- agents are strictly isolated

Use Cases

Scenario	Setup
Single user, single agent	Omit X-Agent-Id (uses "default")
Single user, multiple agents	Each agent sends its own X-Agent-Id
Multi-tenant platform	Each tenant maps to a unique agent ID
CI/CD pipelines	Each pipeline run uses a unique agent ID

Example Configurations

Local Development

kore
# Equivalent to:
# KORE_HOST=127.0.0.1 KORE_PORT=8765 KORE_LOCAL_ONLY=1 kore

Production (LAN Access)

KORE_HOST=0.0.0.0 \
KORE_PORT=8765 \
KORE_LOCAL_ONLY=0 \
KORE_DB_PATH=/var/lib/kore/production.db \
KORE_CORS_ORIGINS="https://myapp.example.com" \
KORE_API_KEY=your-strong-random-key \
kore

Docker

docker run -d \
  -p 8765:8765 \
  -v kore-data:/data \
  -e KORE_HOST=0.0.0.0 \
  -e KORE_LOCAL_ONLY=0 \
  -e KORE_DB_PATH=/data/memory.db \
  ghcr.io/auriti-web-design/kore-memory:latest

Memory-Constrained Environment

KORE_MAX_EMBED_CHARS=4000 \
KORE_EMBED_MODEL=all-MiniLM-L6-v2 \
kore