---
name: better-memory-3edd692a284c
description: "> Semantic memory, intelligent compression, and context management for AI agents"
---

# 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


---
Source attribution: kbarbel640-del
Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/smartpeopleconnected/token-optimizer/skills/better-memory/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 clawdbot

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: kbarbel640-del
Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/smartpeopleconnected/token-optimizer/skills/better-memory/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Development & Engineering
Roles: Backend Developer, Data Scientist, ML / AI Engineer
Specialties: API, Backend, Database
Tools: Tiktoken, @Xenova/Transformers, SQLite
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: c467bd7524e19ef6fb2f619f70c78e4e0e305902f846d9ae8970ecc84609bad0