hanzo-memory

Hanzo Memory (@hanzo/memory) is a TypeScript AI memory service that stores, searches, and retrieves contextual memories using vector embeddings.

Hanzo Memory - AI Memory Service with LanceDB

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-agent.md, hanzo/hanzo-mcp.md

Overview

Hanzo Memory (@hanzo/memory) is a TypeScript AI memory service that stores, searches, and retrieves contextual memories using vector embeddings. It provides a REST API server (Fastify) and a TypeScript client library. The primary backend is LanceDB for vector storage, with 6 embedding provider options including local (ONNX, Candle, llama.cpp) and API-based (OpenAI). Port of the Python memory service with full feature parity.

What it actually is

When to use

Quick reference

| Item | Value | |------|-------| | Repo | github.com/hanzoai/memory | | Package | @hanzo/memory | | Version | 0.1.0 | | Branch | main | | Language | TypeScript | | Runtime | Node.js >= 18 | | Server | Fastify 4 on port 8000 | | DB | LanceDB (default), in-memory (testing) | | Validation | Zod | | Tests | 110 passing (92 unit + 18 integration) | | Test runner | Vitest | | Build | tsup | | Package manager | pnpm | | Docker | Multi-stage (production, test, benchmark, dev) | | CI | GitHub Actions (Linux + macOS matrix) | | License | BSD-3-Clause |

Project structure

hanzoai/memory/
 package.json # @hanzo/memory 0.1.0
 tsconfig.json # TypeScript config
 tsup.config.ts # Build config (tsup)
 vitest.config.ts # Test config
 Dockerfile # 4-stage build
 docker-compose.yml # Server, test, benchmark, dev targets
 .env.example # Configuration template
 src/
 index.ts # Package exports
 server.ts # Fastify REST API server
 client.ts # MemoryClient class
 config.ts # Configuration loading from env
 db/ # Database backends
 models/ # Zod schemas and types
 services/
 memory.ts # Core MemoryService
 embeddings.ts # Embedding provider factory
 embeddings/ # Provider implementations
 llm.ts # LLM provider (OpenAI, Mock)
 index.ts # Service exports
 types/ # TypeScript type definitions
 packages/
 embedding/ # Standalone embedding package
 inference/ # Standalone inference package
 tests/ # Unit and integration tests
 benchmarks/ # Performance benchmarks

Dependencies

From package.json:

API endpoints

Health

Memory operations

Projects

Knowledge base

Chat sessions

Quickstart

As a library

import { MemoryClient } from '@hanzo/memory'

const client = new MemoryClient()

// Store a memory
const memory = await client.remember({
 userid: 'user-123',
 content: 'User prefers dark mode',
 importance: 8
})

// Semantic search
const results = await client.search({
 userid: 'user-123',
 query: 'What are the user preferences?',
 limit: 5
})

As a server

git clone https://github.com/hanzoai/memory.git
cd memory
pnpm install
pnpm run server:dev # Dev mode with auto-reload on port 8000

Docker

docker-compose up memory-server # Production
docker-compose up memory-dev # Development with hot-reload
docker-compose up memory-test # Run tests
docker-compose up memory-benchmark # Run benchmarks

Embedding providers

| Provider | Key | Local | GPU | Dependencies | |----------|-----|-------|-----|-------------| | Mock | mock | Yes | No | None (default) | | OpenAI | openai | No | N/A | OPENAI_API_KEY | | ONNX | onnx | Yes | No | onnxruntime-node | | Transformers.js | transformers | Yes | No | sharp module | | Candle | candle | Yes | Metal (macOS) | Rust + candle-embeddings | | llama.cpp | llama | Yes | CUDA/Metal | llama.cpp binary + model |

Configure via EMBEDDING_PROVIDER env var.

Environment variables

# Database
DB_BACKEND=lancedb # or 'memory'
LANCEDB_URI=./lancedb_data

# Embeddings
EMBEDDING_PROVIDER=mock # mock|openai|onnx|transformers|candle|llama
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2

# OpenAI (optional)
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-3.5-turbo
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Server
HANZO_HOST=0.0.0.0
HANZO_PORT=8000

# Features
STRIP_PII_DEFAULT=false
FILTER_WITH_LLM_DEFAULT=false

Troubleshooting

Related Skills

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: memory, vector-db, lancedb, embeddings, ai, agent Prerequisites: Node.js >= 18, pnpm