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

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

## Installation

```bash
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

```javascript
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