better-memory

Better Memory

Semantic memory, intelligent compression, and context management for AI agents

Package: better-memory

Description: Prevents context limit amnesia with real embeddings, priority-based compression, and identity persistence.

Key Capabilities

• Vector-based memory storage using local embeddings
• Semantic retrieval through similarity matching
• Automatic deduplication (exact hash + cosine similarity >0.9)
• Token-budget-aware retrieval
• User identity persistence across sessions
• Intelligent compression when approaching limits

Dependencies

{
  "@xenova/transformers": "^2.x",
  "tiktoken": "^1.x",
  "sql.js": "^1.x"
}

Installation

cd ~/.clawdbot/skills/better-memory && npm install

Configuration

Parameter	Default	Description
dataDir	~/.better-memory	Storage location
contextLimit	128000	Maximum tokens
tokenEncoding	cl100k_base	Token encoder
warningThreshold	0.75	75% warning
compressThreshold	0.85	85% auto-compress
emergencyThreshold	0.95	95% emergency

Basic Usage

const { ContextGuardian } = require('better-memory');

// Initialize with token budget
const guardian = new ContextGuardian({
  contextLimit: 128000
});

// Store memory with priority
await guardian.store({
  content: "User prefers dark mode",
  role: "user",
  priority: 8
});

// Semantic search
const results = await guardian.search("user preferences");

// Get context within token budget
const context = await guardian.getContext({
  maxTokens: 4000,
  query: "UI preferences"
});

Priority Scoring

Combines multiple signals:

• Role weight: system=7, user=6, assistant=5
• Regex patterns: Important keywords boost score
• Semantic similarity: To query archetypes
• Content length: Reasonable length preferred

Memory Decay

• Age penalty: Older memories score lower
• Access bonus: Frequently accessed memories persist
• Configurable decay rate

Embedding Model

Uses @xenova/transformers with all-MiniLM-L6-v2:

• 384-dimensional vectors
• Local processing (no API calls)
• Fast inference

Storage

SQLite via sql.js (WASM):

• Location: ~/.better-memory/memories.db
• Tables: memories, identity, sessions
• Binary embedding blobs for efficiency

License

MIT