nexusAI/docs/services/shared.md

Shared Package

Package: @nexusai/shared
Location: packages/shared

Purpose

Common utilities and configuration used across all NexusAI services. Keeping these here avoids duplication and ensures consistent behaviour.

Exports

getEnv(key, defaultValue?)

Loads an environment variable by key. If no default is provided and the variable is missing, throws at startup rather than failing silently later.

const { getEnv } = require('@nexusai/shared');

const PORT = getEnv('PORT', '3002');   // optional — falls back to 3002
const DB   = getEnv('SQLITE_PATH');    // required — throws if missing

---

Constants

Tuneable values and shared identifiers are centralised in constants.js rather than hardcoded across services. Import the relevant group by name.

const { QDRANT, COLLECTIONS, EPISODIC } = require('@nexusai/shared');

QDRANT

Vector store configuration. Values here must stay in sync with the embedding model and Qdrant collection setup.

Key	Value	Description
DEFAULT_URL	http://localhost:6333	Fallback Qdrant URL if QDRANT_URL env var is not set
VECTOR_SIZE	768	Output dimensions of nomic-embed-text
DISTANCE_METRIC	'Cosine'	Similarity metric used for all collections
DEFAULT_LIMIT	10	Default top-k for vector searches

COLLECTIONS

Canonical Qdrant collection names. Used by both the semantic layer and any service that constructs Qdrant queries directly.

Key	Value
EPISODES	'episodes'
ENTITIES	'entities'
SUMMARIES	'summaries'

EPISODIC

Default pagination and result limits for SQLite episode queries.

Key	Value	Description
DEFAULT_RECENT_LIMIT	10	Default number of recent episodes to retrieve
DEFAULT_PAGE_SIZE	20	Default episodes per page for paginated queries
DEFAULT_SEARCH_LIMIT	10	Default number of FTS search results to return