memlight

Embedded vector memory for AI agents. It runs inside your process, stores on the local machine, and works with no configuration. There is no server to run, no API key to set, and nothing to wire up before the first store.

It is built on PGlite (Postgres compiled to WebAssembly) with pgvector for similarity search, and ships a local embedding model so semantic recall works out of the box.

Quick start

import { createMemoryProvider } from 'memlight'

const memory = await createMemoryProvider()

await memory.store({
  content: 'Matt prefers concise answers with examples',
  tags: ['preference', 'communication'],
  importance: 0.8,
})

const hits = await memory.recall({ query: 'how does Matt like to be talked to' })
// hits[0].content -> 'Matt prefers concise answers with examples'

That is the whole setup. No data directory, no embedder, no keys.

Install

npm add memlight
pnpm add memlight
bun add memlight

Requires Node 22 or newer.

What it is

• Zero config. A bundled local embedder and an automatic storage location mean a working memory in two lines.
• Semantic recall. Real cosine similarity over pgvector, blended with keyword overlap, tag overlap, and recency.
• Local and private. Everything runs in process. No network at query time, no third party, no key.
• Embedded. The whole database lives in one directory under the user's home. No Postgres server, no Docker, no native build.
• Swappable. Bring your own embedder (Ollama, OpenAI, anything) when you want to.

What it is not

• Not a multi-process database. PGlite is single writer. One process owns a store at a time.
• Not a distributed system. When your data outgrows a single machine, the schema is ordinary Postgres, so pg_dump and restore into a real Postgres with pgvector and your code keeps working.

Defaults

Concern	Default	Override
Embedder	Xenova/bge-small-en-v1.5, 384 dims, local	embedder option
Storage	OS app-data dir, namespaced by name	dataDir, name, scope
Recall	Hybrid: semantic + keyword + tag + recency	weights option
Delete	Soft delete, recoverable	delete(id, { hard: true })

The model downloads once on first use and is cached on disk. After that it loads in about a second with no network.

Storage location

memlight stores in the operating system's app-data directory, not in your repo or working directory. Pick a logical location with name (the app) and an optional scope (a project), and memlight resolves the real path for you.

// <os-data>/akemi
const akemi = await createMemoryProvider({ name: 'akemi' })

// <os-data>/homurai/mattweberio-homurai
const project = await createMemoryProvider({ name: 'homurai', scope: 'mattweberio/homurai' })

// exact path, your call
const custom = await createMemoryProvider({ dataDir: '/srv/data/memory' })

The os-data root by platform:

Platform	Root
Linux and others	$XDG_DATA_HOME or ~/.local/share
macOS	~/Library/Application Support
Windows	%APPDATA% or ~/AppData/Roaming

API

interface MemoryProvider {
  store(input: StoreInput, options?: StoreOptions): Promise<StoreResult>
  recall(query: RecallQuery): Promise<MemoryRecord[]>
  list(filter?: ListFilter): Promise<MemoryRecord[]>
  get(id: string): Promise<MemoryRecord | null>
  update(id: string, input: UpdateInput): Promise<MemoryRecord | null>
  delete(id: string, options?: DeleteOptions): Promise<boolean>
  restore(id: string): Promise<boolean>
  checkDuplicate(content: string, threshold?: number): Promise<DuplicateCheck>
  associate(fromId: string, toId: string, relation: string, strength?: number): Promise<MemoryEdge>
  neighbors(id: string): Promise<MemoryEdge[]>
  count(): Promise<number>
  export(format?: 'jsonl'): Promise<string>
  import(data: string, format?: 'jsonl'): Promise<{ imported: number }>
  close(): Promise<void>
}

store

Field	Type	Notes
id	string	Optional. A UUID is generated when omitted. Pass an id to upsert.
content	string	Required. Empty content throws.
tags	string[]	Default []. Recall can filter to memories that have all of a set of tags.
importance	number	0 to 1. Nudges recall ranking.
type	string	Free-form label such as Decision, Preference.
metadata	Record<string, unknown>	Stored as JSON. Anything serializable.

Pass { dedup: true } as the second argument to skip the write and return the existing memory when a near-duplicate is already stored.

recall

Field	Type	Notes
query	string	Natural language. Embedded and ranked by similarity.
tags	string[]	Only return memories that have all of these tags.
limit	number	Default 20.
minScore	number	Minimum semantic similarity 0 to 1. Default 0.
weights	Partial<SearchWeights>	Override the ranking blend for this query.

Recall also accepts the structured filter fields shared with list (type, tagMatch, minImportance, maxImportance, createdAfter, createdBefore). They restrict the candidate set before ranking, so recall is a filtered semantic search.

Recall ranks by a blend of semantic similarity, keyword overlap, tag overlap, and recency, with a small lift for higher importance. The default weights are { semantic: 0.45, keyword: 0.35, tag: 0.2 } and they are renormalized across whichever signals a query actually uses. With a query and no embedder, recall ranks by keyword overlap. With no query, it returns the newest memories matching tags.

list

A structured, non-vector query for when you want exact filtering and ordering rather than relevance ranking. Use recall to answer "what is most relevant to this query"; use list to answer "give me these memories, filtered and sorted".

Field	Type	Notes
type	string	Restrict to one type.
tags	string[]	Restrict to these tags.
tagMatch	'all' | 'any'	'all' (default) requires every tag; 'any' requires at least one.
minImportance / maxImportance	number	Inclusive importance bounds (0 to 1).
createdAfter / createdBefore	string	Inclusive ISO timestamp bounds.
includeDeleted	boolean	Include soft-deleted memories. Default false.
sortBy	string	createdAt (default), updatedAt, importance, accessCount, or lastAccessed.
sortDirection	'asc' | 'desc'	Default desc.
limit / offset	number	Paging.

const recent = await memory.list({ type: 'note', tags: ['project'], minImportance: 0.5, limit: 20 })

config

Field	Type	Notes
dataDir	string	Explicit path. Overrides name and scope. 'memory://' is ephemeral.
name	string	App name for the default path. Default memlight.
scope	string	Optional project id for per-project isolation.
embedder	Embedder | 'none'	Omit for the bundled default. 'none' is keyword and tag only. A function brings your own.
vectorDim	number	Defaults to the embedder's output (384 for the bundled default). Fixed at the first store.
weights	Partial<SearchWeights>	Default ranking weights for every recall.

Swapping the embedder

The embedder is just (text: string) => Promise<number[]>. Pass your own to use a different model, and set vectorDim to match its output.

// Ollama, local, free
const memory = await createMemoryProvider({
  vectorDim: 768,
  embedder: async (text) => {
    const res = await fetch('http://localhost:11434/api/embeddings', {
      method: 'POST',
      body: JSON.stringify({ model: 'nomic-embed-text', prompt: text }),
    })
    const { embedding } = await res.json()
    return embedding
  },
})

// Keyword and tag matching only, no vectors
const memory = await createMemoryProvider({ embedder: 'none' })

In-memory mode

Pass 'memory://' for an ephemeral database with no disk writes. Useful for tests.

const memory = await createMemoryProvider({ dataDir: 'memory://' })

Graph edges

Relate memories to each other and read the edges back.

await memory.associate(planId, blockerId, 'blocked_by', 0.8)
const edges = await memory.neighbors(planId)

Soft delete and restore

Delete is recoverable by default. A soft-deleted memory drops out of recall, get, and count, and comes back with restore. Pass { hard: true } to remove it for good.

await memory.delete(id)                  // recoverable
await memory.restore(id)                 // back
await memory.delete(id, { hard: true })  // gone

Backup

const dump = await memory.export('jsonl')   // every live memory and edge
await other.import(dump)                     // load it elsewhere

Export carries content, tags, importance, type, metadata, and edges. Embeddings are rebuilt on import, so a backup is portable across embedders.

Limitations

• Single process. Opening the same store from two processes at once is unsupported.
• Recall reranks a candidate pool. For very large stores the keyword and recency rerank runs over a bounded candidate set, not the entire table. Personal scale (tens of thousands of memories) is comfortable.
• Importance and recency are heuristics. They nudge ranking; they do not expire memories. There is no TTL yet.

License

MIT. See LICENSE.

Source and issues

github.com/mattweberio/memlight