zayra-memory

The memory engine of ZAYRA AI. It manages conversation memory, user memory, project memory, AI context memory, and saved knowledge for the ZAYRA ecosystem.

This is version 0.0.1: memory management system only — no frontend/UI code.

Installation

npm install zayra-memory

Usage

import { MemoryManager } from "zayra-memory";

const memory = new MemoryManager();

await memory.save({ content: "User likes dark UI" });

Memory types

| Type | Purpose | Example | | --- | --- | --- | | short_term | Current conversation context | Recent messages | | long_term | Important, durable user information | Preferences | | project | Project-related information | ZAYRA settings | | temporary | Session-based data | Cleared with clearSession() |

import { MemoryType } from "zayra-memory";

await memory.save({
  content: "User prefers dark theme",
  type: MemoryType.LONG_TERM,
  importance: 8,
});

Memory structure

Every stored memory has this shape:

{
  "id": "memory_id",
  "type": "long_term",
  "content": "User prefers dark theme",
  "importance": 8,
  "createdAt": "2026-07-02T10:00:00.000Z",
  "updatedAt": "2026-07-02T10:00:00.000Z",
  "metadata": {}
}

importance ranges from 1 (least important) to 10 (most important). If omitted, it defaults to 5.

Saving, retrieving, updating, deleting

const saved = await memory.save({ content: "User's project is called Zayra" });

const one = await memory.retrieve(saved.id);
const all = await memory.retrieveAll();
const projectMemories = await memory.retrieveAll({ type: "project" });

const updated = await memory.update(saved.id, { importance: 9 });

await memory.delete(saved.id);

Searching memories

const results = await memory.searchMemories("dark theme", {
  type: "long_term",
  minImportance: 5,
  limit: 10,
});

Search is keyword-based in 0.0.1 (matches whole tokens in memory content) with filtering by type and importance range, and results are ranked by importance. Semantic search / embeddings are planned for a future version.

Memory controls

Per-spec user-facing controls over stored memories:

await memory.view(id);          // read a memory without modifying it
await memory.update(id, {...}); // update a memory
await memory.delete(id);        // delete a single memory
await memory.clear();           // delete ALL memories
await memory.clear({ type: "temporary" }); // delete only one type
await memory.clearSession();    // shorthand for clearing temporary memory

Ranking

Every memory's numeric importance (1-10) maps onto a priority band the AI should use to decide what matters most:

| Priority | Importance range | Example | | --- | --- | --- | | High | 8-10 | Important preferences | | Medium | 4-7 | Project details | | Low | 1-3 | Temporary information |

import { importanceToPriority, rankByImportance, groupByPriority } from "zayra-memory";

importanceToPriority(9); // "high"

const ranked = rankByImportance(memories);       // highest importance first
const grouped = groupByPriority(memories);        // { high: [...], medium: [...], low: [...] }

Context Builder

Turns stored memories into AI-ready context, following the documented flow:

Memory -> Context Builder -> AI Router

const context = await memory.buildContext({ maxMemories: 20 });

context.memories;          // ranked Memory[] used to build this context
context.groupedByPriority; // { high, medium, low }
context.text;              // formatted plain-text block, ready for a prompt

context.text looks like:

- [long_term] User prefers dark theme
- [project] Project is called Zayra
- [short_term] User just asked about pricing

A future zayra-ai-router package can consume this shape directly.

Storage

Version 0.0.1 supports local storage via a JSON database file (zayra-memory.db.json by default, written next to your working directory unless overridden). Writes are done via a temp-file-then-rename so a crash mid-write can't corrupt the database.

const memory = new MemoryManager({
  cwd: "/path/to/data",
  fileName: "my-memories.json",
});

SQLite, vector database, and cloud storage backends are planned for future versions — storage.js is intentionally the only layer that would need to change.

Privacy

zayra-memory is designed to keep private data protected: memories are stored locally by default, nothing is transmitted anywhere by this package, and consumers are expected to apply their own access permissions before exposing stored memories to a user or another system.

Errors

• MemoryError — base error class; thrown for invalid memory data, missing memories, etc.
• StorageError — extends MemoryError; thrown for database/storage failures (read/write/corrupt file).

import { MemoryError, StorageError } from "zayra-memory";

try {
  await memory.update("nonexistent-id", { content: "x" });
} catch (err) {
  if (err instanceof MemoryError) {
    console.error(err.message);
  }
}

Project structure

zayra-memory/
  src/
    index.js     # public entry point
    memory.js    # Memory entity class
    manager.js   # MemoryManager + ContextBuilder
    storage.js   # memory-aware storage abstraction
    database.js  # low-level JSON file persistence
    search.js    # MemorySearch (keyword search + filtering)
    ranking.js   # importance -> priority ranking
    types.js     # MemoryType, MemoryPriority enums
    errors.js    # MemoryError, StorageError
  package.json
  README.md

API reference

class MemoryManager

| Method | Description | | --- | --- | | new MemoryManager(options?) | options.cwd, options.fileName, options.filePath, options.storage. | | save(input) | Saves a new memory. Returns the created Memory. | | retrieve(id) | Gets a single memory by id, or null. | | retrieveAll(options?) | Gets all memories, optionally filtered by type. | | update(id, changes) | Updates a memory's fields. Throws if not found. | | delete(id) | Deletes a single memory. | | searchMemories(query, options?) | Keyword search with filters, ranked by importance. | | view(id) | Alias for retrieve(). | | clear(options?) | Deletes all memories, or only a given type. | | clearSession() | Shorthand for clear({ type: "temporary" }). | | buildContext(options?) | Builds AI-ready context via ContextBuilder. |

Other exports

ContextBuilder, Memory, MemoryStorage, JsonDatabase, MemorySearch, MemoryType, MemoryPriority, importanceToPriority(), rankByImportance(), rankByRecency(), groupByPriority(), MemoryError, StorageError

Future compatibility

Designed to connect with zayra-core, zayra-config, zayra-train, zayra-ai-router, and zayra-sdk as the ZAYRA ecosystem grows.

License

MIT