Skip to main content
@moss-dev/moss / SessionIndex

​
SessionIndex

A local-first, in-process index for real-time indexing and querying. All operations (addDocs, deleteDocs, query) run in process memory with no cloud round-trip per operation. Call pushIndex() to persist the session to the cloud. Construct a session with MossClient.session(); the constructor is not used directly.

​
Example

import { MossClient } from '@moss-dev/moss';

const client = new MossClient('your-project-id', 'your-project-key');

const session = await client.session('chat-session-123');
await session.addDocs([{ id: '1', text: 'Customer asked about billing' }]);
const results = await session.query('billing question');
await session.pushIndex();

​
Accessors

PropertyTypeDescription
namestringThe session index name. Identifies the cloud index on pushIndex / loadIndex.
docCountnumberNumber of documents currently in the local session.
modelIdMossModelThe embedding model the session is configured for.

​
Methods

​
addDocs()

addDocs(docs, options?): Promise<{ added: number; updated: number }>
Adds or updates documents in the local session index. For built-in models, embeddings are generated locally. For modelId: "custom", each document must carry an embedding.

​
Parameters

ParameterTypeDescription
docsDocumentInfo[]Documents to add or update.
options?MutationOptionsMutation options (e.g. upsert).

​
Returns

Promise<{ added: number; updated: number }>

​
deleteDocs()

deleteDocs(docIds): Promise<number>
Deletes documents from the local session by id. Returns the number removed.

​
Parameters

ParameterTypeDescription
docIdsstring[]Document ids to delete.

​
Returns

Promise<number>

​
getDocs()

getDocs(options?): Promise<DocumentInfo[]>
Fetches documents currently in the local session.

​
Parameters

ParameterTypeDescription
options?GetDocumentsOptionsPass docIds to filter.

​
Returns

Promise<DocumentInfo[]>

​
query()

query(query, options?): Promise<SearchResult>
Hybrid (keyword + semantic) search over the local session index, entirely in-memory. For modelId: "custom", an explicit options.embedding is required.

​
Parameters

ParameterTypeDescription
querystringThe search query text.
options?QueryOptionsQuery options (topK, alpha, embedding, filter).

​
Returns

Promise<SearchResult>

​
loadIndex()

loadIndex(indexName, options?): Promise<number>
Loads an existing cloud index into the session by name. With options.autoRefresh = true, the SDK polls the cloud index and pulls newer versions in on subsequent reads (paused while the session has un-pushed local edits). Returns the number of documents loaded.

​
Parameters

ParameterTypeDescription
indexNamestringName of the cloud index to load into the session.
options?LoadSessionOptionsAuto-refresh settings.

​
Returns

Promise<number>

​
pushIndex()

pushIndex(): Promise<PushIndexResult>
Uploads the session to the cloud, creating or replacing the index with the same name. Documents are pushed with their locally-computed embeddings; no server-side re-embedding.

​
Returns

Promise<PushIndexResult>

​
saveToDisk()

saveToDisk(cachePath): Promise<void>
Persists the session to <cachePath>/<name>/ for offline reuse without a cloud round-trip.

​
Parameters

ParameterTypeDescription
cachePathstringDirectory to write the session to.

​
loadFromDisk()

loadFromDisk(cachePath): Promise<number>
Restores a session previously written by saveToDisk. Returns the number of documents loaded.

​
Parameters

ParameterTypeDescription
cachePathstringDirectory a session was saved to.

​
Returns

Promise<number>