@kuindji/memory-domain

Stores memories as nodes in a directed graph structure with domain-driven design principles, enabling relationships between memory entities to be explicitly modeled and traversed. Uses embedding vectors to index memory content semantically, allowing memories to be retrieved not just by exact match but by conceptual similarity. The graph structure persists relationships between domain entities (e.g., users, conversations, events) as first-class citizens rather than denormalized fields.

Implements vector similarity search by computing embeddings for memory queries and comparing them against stored memory embeddings using distance metrics (cosine, Euclidean). Returns ranked results ordered by semantic relevance rather than keyword overlap. Supports configurable embedding models and distance functions, allowing swapping between different embedding providers without changing query logic.

Provides an abstraction layer for memory persistence that decouples the domain model from storage implementation. Developers can implement custom storage adapters (file-based, database, cloud storage) by conforming to a standard interface, enabling memories to be persisted to any backend without changing application code. Supports both synchronous and asynchronous persistence operations.

Allows defining typed relationships between memory entities (e.g., 'mentions', 'references', 'contradicts') and traversing the graph to discover connected memories. Relationships are first-class objects with properties, enabling rich semantic connections beyond simple foreign keys. Supports depth-limited traversal, filtering by relationship type, and aggregating results across multiple paths.

Tracks memory creation, modification, and access timestamps, enabling time-based queries and memory aging strategies. Supports marking memories as archived, deleted, or expired, and provides hooks for lifecycle events (on-create, on-update, on-access). Enables implementing memory decay (older memories ranked lower) and retention policies without manual cleanup.

Provides a framework for defining domain models (entities, value objects, aggregates) with type safety, enabling developers to structure memories according to domain concepts rather than generic key-value pairs. Supports validation, serialization, and custom methods on domain objects. Type definitions enable IDE autocomplete and compile-time checking for memory operations.

Supports performing multiple memory operations (create, update, delete, relate) as a logical unit with rollback on failure. Implements optimistic concurrency control or pessimistic locking depending on configuration. Enables efficient bulk operations without individual round-trips to storage, useful for syncing large memory sets or performing complex multi-step memory updates.

Provides a query API for filtering memories by properties, relationships, and temporal criteria, with support for aggregation operations (count, group-by, statistics). Queries are composable and can be combined with semantic search. Supports both simple property filters and complex nested queries on related entities.

Automatically selects and ranks relevant memories to fit within an LLM's context window, using a combination of semantic similarity, recency, and importance scores. Provides utilities to format selected memories for LLM prompts and manage token budgets. Supports context prioritization strategies (e.g., prioritize recent memories, prioritize high-importance memories).

Detects semantically similar or duplicate memories and provides strategies for merging or resolving conflicts. Supports fuzzy matching on properties and embedding-based similarity detection. Allows defining custom conflict resolution rules (e.g., keep newest, merge properties, flag for manual review). Prevents memory bloat from repeated information.