openclaw-memory-core

# OpenClaw Memory Core

Shared library powering OpenClaw's memory plugins (`openclaw-memory-brain` and `openclaw-memory-docs`). Provides three core modules:

## Redaction

Automatically detects and redacts secrets before they reach memory storage. Covers:
- API keys (OpenAI, Anthropic, Stripe, Google, GitHub PATs)
- AWS credentials (access keys, secret keys)
- Azure storage keys, HashiCorp Vault tokens
- JWTs, Bearer tokens, PEM private key blocks

Usage: pipe any text through the redactor before storing — secrets are replaced with safe `[REDACTED:TYPE]` placeholders.

## JSONL Store

Local file-based memory store using append-only `.jsonl` files. Features:
- CRUD for memory items (kinds: `fact`, `decision`, `doc`, `note`)
- Expiration support (`expiresAt` field)
- Semantic search via cosine similarity on embeddings
- No external database required — everything lives in flat files

## Embeddings

Deterministic, offline, dependency-free text embedder (`HashEmbedder`):
- FNV-1a hash-based vector generation (default 256 dimensions)
- L2 normalization for cosine similarity search
- No API calls, no model downloads — works fully offline
- Not SOTA semantics, but stable and fast for local vector search

## Integration

This is a dependency library, not a standalone plugin. Install it as a package dependency:

```bash
npm install @elvatis_com/openclaw-memory-core
```

Used internally by `openclaw-memory-brain` (auto-capture) and `openclaw-memory-docs` (explicit capture).

# @elvatis_com/openclaw-memory-core

Core utilities for building OpenClaw memory plugins - redaction, embeddings, and JSONL-backed vector search.

## Installation

```bash
npm install @elvatis_com/openclaw-memory-core
```

Requires Node.js 18+.

## Quick start

```ts
import {
  JsonlMemoryStore,
  createEmbedder,
  DefaultRedactor,
  uuid,
} from "@elvatis_com/openclaw-memory-core";

// 1. Set up the store
const embedder = createEmbedder();
const store = new JsonlMemoryStore({
  filePath: "./data/memories.jsonl",
  embedder,
});

// 2. Redact secrets before storing
const redactor = new DefaultRedactor();
const { redactedText } = redactor.redact("My API key is sk-proj-abc123def456ghi789");

// 3. Store a memory
await store.add({
  id: uuid(),
  kind: "note",
  text: redactedText,
  createdAt: new Date().toISOString(),
  tags: ["api", "credentials"],
});

// 4. Search by natural language
const results = await store.search("API key");
console.log(results[0]?.item.text);
// => "My API key is [REDACTED:OPENAI_KEY]"
```

## API reference

All exports are available from the package root:

```ts
import { /* any export */ } from "@elvatis_com/openclaw-memory-core";
```

---

### Types

#### `MemoryKind`

```ts
type MemoryKind = "fact" | "decision" | "doc" | "note";
```

The four supported item categories.

#### `MemoryItem`

```ts
interface MemoryItem {
  id: string;
  kind: MemoryKind;
  text: string;
  createdAt: string;          // ISO 8601
  expiresAt?: string;         // ISO 8601 - optional TTL
  source?: {
    channel?: string;
    from?: string;
    conversationId?: string;
    messageId?: string;
  };
  tags?: string[];
  meta?: Record<string, unknown>;
}
```

The fundamental data unit stored by a `MemoryStore`.

#### `SearchHit`

```ts
interface SearchHit {
  item: MemoryItem;
  score: number;  // 0..1 (1 = best match)
}
```

Returned by `store.search()`. Results are sorted by score descending.

#### `SearchOpts`

```ts
interface SearchOpts {
  limit?: number;...