Skip to content

API Reference

Setup

MemoryService is the single entry point. It owns a MemoryPool, a LinkPool, a TextEmbeddingProvider, and the selection and linking strategies.

import {
    MemoryConfiguration,
    MemoryService,
    HuggingFaceEmbeddingProvider
} from '@johannes.latzel/llm-chat-memory';

const config = new MemoryConfiguration();
const embedder = new HuggingFaceEmbeddingProvider({ model: config.embeddingModel });
const service = new MemoryService(config, embedder);
await service.init();

const memories = await service.recall('what do I know about the project?');

MemoryConfiguration.embeddingModel is a default value loaded from LLM_CHAT_MEMORY_EMBEDDING_MODEL. It is not passed to a provider automatically; pass it to HuggingFaceEmbeddingProvider({ model }) or use a custom TextEmbeddingProvider.

MemoryConfiguration

new MemoryConfiguration(memoryDir?, maxInjectPerMessage?, maxInjectPerSendLoop?)

The three arguments override the corresponding fields. Every other field is initialized from its environment variable or default.

Param Type Default Description
memoryDir string ./memories Directory for memory JSON files
maxInjectPerMessage number 2 Default recall cap per message
maxInjectPerSendLoop number 5 Cumulative cap per send loop

Fields

Field Type Default Env Description
memoryDir string ./memories LLM_CHAT_MEMORY_DIR Directory for memory JSON files
maxInjectPerMessage number 2 LLM_CHAT_MEMORY_MAX_INJECT_PER_MESSAGE Default recall cap per message
maxInjectPerSendLoop number 5 LLM_CHAT_MEMORY_MAX_INJECT_PER_SEND_LOOP Cumulative cap per send loop
maxInjectionContentLength number 500 LLM_CHAT_MEMORY_MAX_INJECTION_CONTENT_LENGTH Serialized JSON limit for get_memory
similarityGate number 0.4 LLM_CHAT_MEMORY_SIMILARITY_GATE Minimum cosine similarity
embeddingModel string Xenova/all-MiniLM-L6-v2 LLM_CHAT_MEMORY_EMBEDDING_MODEL Default model ID for HuggingFaceEmbeddingProvider
minSummaryLength number 50 LLM_CHAT_MEMORY_MIN_SUMMARY_LENGTH Minimum summary length
maxSummaryLength number 600 LLM_CHAT_MEMORY_MAX_SUMMARY_LENGTH Base maximum summary length
summaryContentRatio number 0.2 none Summary-to-content ratio used by the effective maximum
recencyHalfLife number 3600 LLM_CHAT_MEMORY_RECENCY_HALF_LIFE Recency decay half-life in seconds
similarityWeight number 0.5 none Composite score weight for similarity
pageRankWeight number 0.3 none Composite score weight for PageRank
recencyWeight number 0.2 none Composite score weight for recency
mmrDiversityTradeoff number 0.7 none MMR relevance/diversity trade-off

The effective summary maximum is max(minSummaryLength, maxSummaryLength, round(summaryContentRatio * content.length)). With the defaults that is at least 50 characters and at most max(600, 20% of content length).

MemoryService

new MemoryService(config, embedder, strategy?, store?)

Param Type Default Description
config MemoryConfiguration required Service configuration
embedder TextEmbeddingProvider required Embedding provider
strategy SelectionStrategy MMRSelectionStrategy Result selection strategy
store ObjectStore<MemoryJSON> JsonFileStore over config.memoryDir Memory persistence backend

init()

Load memory files, rebuild the link graph, and run PageRank scoring. Idempotent.

Returns Promise<void>.

memories()

Returns MemoryPoolInterface: the CRUD and embedding interface for the pool. Recall is on MemoryService.recall().

Returns LinkPoolInterface: the link graph interface.

recall(message, maxInject?)

Param Type Default Description
message string required Natural-language query
maxInject number config.maxInjectPerMessage Result cap; overrides the configured default

Runs pool recall, selects memories, and marks the selected memories as recalled. Returns Promise<ReadonlyMemory[]>.

score()

Recompute PageRank over the link graph and persist updated scores. Returns Promise<void>.

hookInto(chatService)

Param Type Default Description
chatService RecallHookTarget required Chat service to attach passive recall to; a ChatService satisfies it

Registers callbacks on beforeSendLoop and afterSend. Returns a MemoryHook with dispose() to unregister them.

hook()

Returns MemoryServiceHookBuilder for memory and link pool events. See Hooks.

getEmbedder()

Returns the TextEmbeddingProvider used by the service.

get config

Returns the MemoryConfiguration used by the service.

get linker

Returns the semantic Linker. Call sync() to recompute semantic links.

MemoryPoolInterface

all()

Returns Promise<ReadonlyMemory[]>.

get(id)

Param Type Default Description
id string required Memory ID

Returns Promise<ReadonlyMemory | undefined>.

has(id)

Param Type Default Description
id string required Memory ID

Returns boolean.

create(label, input)

Param Type Default Description
label string required Label used to derive the ID
input CreateMemoryInput required { content, summary, tags? }

Returns Promise<Memory>.

update(id, input)

Param Type Default Description
id string required Memory ID
input UpdateMemoryInput required { content?, summary?, tags? }

Changes to content or tags invalidate the cached embedding. Returns Promise<Memory>.

delete(id)

Param Type Default Description
id string required Memory ID

Deletes the memory and its file. It does not remove links; call service.links().isolate(id) separately. Returns Promise<void>.

ensureEmbeddings()

Recompute stale or missing embeddings. Returns Promise<void>.

LinkPoolInterface

link(from, to, undirected?)

Param Type Default Description
from string required Source memory ID
to string required Target memory ID
undirected boolean false Create the link in both directions

Returns Promise<void>.

link(from, targets, undirected?)

Param Type Default Description
from string required Source memory ID
targets string[] required Target memory IDs
undirected boolean false Create the links in both directions

Returns Promise<string[]> with the targets that were linked.

unlink(from, to, undirected?)

Param Type Default Description
from string required Source memory ID
to string required Target memory ID
undirected boolean false Remove the link in both directions

Removes constant and semantic links. Returns Promise<void>.

unlink(from, targets, undirected?)

Param Type Default Description
from string required Source memory ID
targets string[] required Target memory IDs
undirected boolean false Remove the links in both directions

Returns Promise<void>.

isolate(id)

Param Type Default Description
id string required Memory ID

Removes every link involving the memory. Returns Promise<void>.

Hooks

const handle = service.hook().memories().onCreate().do(({ id }) => {
    // handle the event
});
handle.dispose();

service.hook().links().onLink().do(({ from, to }) => {
    // handle the event
});
Builder Events
service.hook().memories() onCreate, onUpdate, onDelete, onRecall
service.hook().links() onLink, onUnlink

Each do(callback) returns a Hook with dispose().

Memory Fields

A Memory exposes its fields via native get/set accessors (mem.content, mem.score, etc.). Fields with a setter are writable; id and createdAt are read-only and remain plain methods.

Field Accessor Writable
id mem.id() No
content mem.content (get/set) Yes
summary mem.summary (get/set) Yes
tags mem.tags (get/set) Yes
score mem.score (get/set) Yes
embedding (cached vector) mem.embedding (get/set) Yes
links mem.links (get/set) Yes
createdAt mem.createdAt() No
changedAt mem.changedAt (get/set) Yes
recalledAt mem.recalledAt (get/set) Yes
cachedAt mem.cachedAt (get/set) Yes

See Architecture for the recall pipeline and Hooks for passive injection.