Agent Memory Manager

Run & Deploy

Run & Deploy Instructions — Agent Memory Manager

Requirements

Node.js >= 20 (developed/verified on v24).
No database server required for the default and PGlite paths.
For an external store: a Postgres instance with the vector (pgvector)

extension available.

Local run

cd delivery-package/agent-memory-manager
npm install
npm run build
npm test                 # unit suite (24 tests, includes real pgvector)
node verify.mjs          # full verification harness -> verification-report.*
npm run example          # runnable fleet-monitoring example

Embed in an application

The module ships as ESM. After npm run build, import from dist/src/index.js (or consume the package by name once published to your registry):

import { MemoryManager, AgentMemoryWrapper } from '@forge/agent-memory-manager';

Choosing a store

Scenario	Store	Durable	Notes
Tests / ephemeral agents	`InMemoryStore` (default)	No	Zero dependencies.
Single host, durable	`createPgliteMemoryStore({ dataDir })`	Yes	Embedded Postgres+pgvector (WASM).
Shared / multi-host	`new PgVectorStore(pgPool, …)`	Yes	External Postgres server via `pg`.

External Postgres

# example: a Postgres image with pgvector available
export DATABASE_URL=postgres://user:pass@host:5432/agents

import pg from 'pg';
import { PgVectorStore, MemoryManager } from '@forge/agent-memory-manager';

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const store = new PgVectorStore(pool, { dimensions: 256 });
await store.init();   // CREATE EXTENSION vector + table + indexes (idempotent)

const memory = new MemoryManager({ store, namespace: 'prod-agent' });
await memory.init();

Install pg in your application (npm install pg). It is an optional
dependency of this package.

Configuration knobs

tiers: per-tier capacity, halfLifeMs, minImportance.
relevanceWeights: weights for similarity/recency/importance/frequency/tags.
promoteThreshold: cosine at which a retrieved memory is pulled to hot.
autoMaintain: disable to run maintain() on your own schedule.
embeddings / summarizer / logger / metrics / sync: inject your own.

Long-running agent guidance

Run a periodic memory.maintain() (e.g. every 60s) so decay/eviction keeps

the hot tier bounded even during quiet periods.

Periodically summarizeThread(threadId, { compact: true }) on closed

incidents/episodes to compress raw lines into a retained summary.

Export memory.metrics.snapshot() to your metrics backend on an interval.

Fleet deployment

Give every node a unique nodeId and a shared namespace.
Provide a shared SyncBus. The in-process bus suits a single process; for a

real fleet implement SyncBus over Redis/NATS/Kafka (disclosed seam — see proof/LIMITATIONS.md).

Use shareScope: 'fleet' (or AgentMemoryWrapper.shareWithFleet) for

knowledge that should propagate; everything else stays node-local.

Shutdown

Call await memory.close() on process exit to release the store/DB connection and unsubscribe from the sync bus.