@polyweave/simplemem (1.0.1)

Published 2026-07-17 14:55:14 +00:00 by Dvorak

Set up this registry in your project .npmrc file:

@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/

To install the package using npm, run the following command:

npm install @polyweave/simplemem@1.0.1

or add it to the package.json file:

"@polyweave/simplemem": "1.0.1"

For more information on the npm registry, see the documentation.

simplemem

SimpleMem-style memory framework built on Polyweave stores.

Published as @polyweave/simplemem.

Synopsis

import { createSimpleMem } from '@polyweave/simplemem';

const mem = createSimpleMem({
  embedder: myEmbedAdapter,
  summarizer: mySummarizerAdapter,
  clusterThreshold: 0.82
});

mem.remember('The user prefers dark mode interfaces', { metadata: { source: 'chat' } });

mem.search('user preferences', { profile: 'session_memory', limit: 5 }, (err, results) => {
  console.log('Recalled:', results);
});

Install

npm install @polyweave/simplemem

Description

The simplemem package provides a comprehensive memory framework built on Polyweave state stores. It supports multi-modal memory storage (text, vectors, trees, graphs, documents) with unified persistence, semantic search, cluster-based consolidation, and JAG (Joint Access Graph) integration for cross-store querying.

Core components include:

SimpleMem — Primary memory system with text storage, vector embeddings, tree-organized hierarchy, fact graph, and document sections. Supports operations: remember, recall, search, forget, consolidate, summarize, and query.
SimpleMem+ — Enhanced variant with additional features: episodic memory, working memory, session memory, and context management.
Persistence — Unified transaction-based persistence via createMemoryTransaction and createMemoryCache with dirty-tracking and snapshot/restore.
Agent Tools — Pre-built tool adapters (createQueryTool, createAskTool, createMemoryToolRouter) that expose memory as callable tools to LLM agents.
Sleuth Integration — Combines simplemem storage with @polyweave/sleuth retrieval for self-improving search over memories.
OM XML DSL — XML-based DSL for structured observation/memory entries with validation.

API

`createSimpleMem(options)`

Creates the primary SimpleMem memory system.

Parameters:

options.embedder — Embedding adapter for vector-based memory search.
options.queryEmbedder — Separate embedding adapter for query encoding (defaults to embedder).
options.compressor(text, done) — Compression function for memory compression.
options.gate(entry, existing, done) — Gate function controlling memory admission.
options.summarizer(entries, done) — Summarization function for memory consolidation.
options.clusterThreshold — Cosine similarity threshold for clustering (default 0.82).
options.minClusterSize — Minimum entries to trigger consolidation (default 3).
options.maxConsolidationMembers — Max entries per consolidation group (default 8).
options.enableVectorStore — Enable vector-based search (default true).
options.enableClusterTree — Enable cluster tree for hierarchical memory.
options.textStore, options.treeStore, options.graphStore, options.documentStore — Inject custom state stores.
options.*StoreOptions — Options forwarded to each store constructor.
options.semanticProfileLimit, options.entityProfileLimit, options.sessionProfileLimit — Per-profile result limits.

Returns: A SimpleMem instance with:

remember(content, metadata, callback) — Store a memory entry.
recall(id, callback) — Retrieve a specific entry by ID.
search(query, options, callback) — Semantic or keyword search.
forget(id, callback) — Remove a memory entry.
consolidate(callback) — Trigger cluster-based memory consolidation.
summarize(range, callback) — Summarize a range of memories.
query(dsl, callback) — Run a structured query against the memory graph.
getStats() — Memory statistics (entry count, vector size, cluster count).
close() — Clean up resources.

Query options: { profile, limit, offset, filter, includeVectors, jag }.

`createAgentHarness(options)`

Creates a SimpleMem agent harness (bt-harness-compatible).

`createSimpleMemTools(options)`

Creates a set of agent tools: query, ask, remember, forget.

Returns: Array of tool adapter objects.

`createSimpleMemToolDefinitions(options)`

Returns tool definition schemas for agent tool registration.

`createMemoryAgent(options)`

Creates a full agent harness with registered memory tools.

`createMemoryTransaction(store)`

Creates a transactional wrapper around a store with begin/commit/rollback.

`createMemoryCache(options)`

Creates a caching layer with dirty tracking and snapshot/restore.

`createJagMemoryStore(options)`

Creates a JAG (Joint Access Graph) memory store for cross-store querying.

`createMemorySleuth(options)`

Combines simplemem storage with sleuth retrieval pipeline.

`createMemorySleuthTool(options)`

Exposes memory-sleuth as a callable tool adapter.

`createLLMReasoner(options)`

Creates an LLM-based reasoning adapter for memory-aware querying.

OM XML DSL

createObservation(type, content, metadata) — Creates an XML-formatted memory observation.
parseObservation(xml) — Parses OM XML back into structured data.
validateObservation(xml) — Validates OM XML structure.

Examples

// Consolidated memory with clustering
const mem = createSimpleMem({
  embedder: myEmbedAdapter,
  clusterThreshold: 0.8,
  minClusterSize: 3
});

mem.remember('User prefers TypeScript', { tags: ['preference', 'language'] });
mem.remember('User dislikes inline styles', { tags: ['preference', 'css'] });
mem.remember('User uses React hooks primarily', { tags: ['preference', 'react'] });

mem.consolidate((err) => {
  mem.search('frontend development preferences', { limit: 3 }, (err, results) => {
    console.log('Consolidated results:', results);
  });
});

// Agent tool integration
import { createSimpleMemTools, createMemoryAgent } from '@polyweave/simplemem';

const tools = createSimpleMemTools({ memory: mem });
const agent = createMemoryAgent({
  memory: mem,
  tools,
  apiKey: process.env.API_KEY
});

agent.sink.write({ type: 'TOOL_CALL', content: { name: 'memory_query', query: 'deployment procedure' } });

Tests

npm test

Tests cover memory creation with various store configurations, remember/recall/forget operations, semantic search with and without embeddings, cluster-based consolidation, summarization, JAG integration, transaction begin/commit/rollback, caching dirty tracking and snapshot/restore, agent tool integration, OM XML DSL parsing and validation, and sleuth integration.

Requirements

Node.js 18 or later. ESM only.

Caveats

Memory performance scales with store size; vector searches are O(n) for brute-force (consider approximate nearest-neighbor stores for large datasets).
Cluster consolidation uses cosine similarity with embeddings; without an embedder, consolidation is text-overlap based and less accurate.
Transactional persistence stores are in-memory by default. For durable persistence, inject persistent state store implementations.
The OM XML DSL is a convenience format; it does not enforce XML schema validation beyond basic structure checks.

License

MIT

Dependencies

ID	Version
peggy	^4.2.0

Development Dependencies

ID	Version
@rigor/core	*
@stryker-mutator/core	^8.7.1
fast-check	^2.25.0

Peer Dependencies

ID	Version
@polyweave/durability	*
@polyweave/openai	*
@polyweave/self-improving	*
@polyweave/state	*
@polyweave/state-search	*

polyweave memory simplemem graph retrieval

Details

npm

2026-07-17 14:55:14 +00:00

266

John Dvorak

SEE LICENSE IN LICENSE

latest

44 KiB

Assets (1)

simplemem-1.0.1.tgz 44 KiB

Versions (3) View all

1.0.1

2026-07-17

1.0.3

2026-07-10

1.0.2