Hy-Memory

Overview

Hy Memory is a production-grade dual-system cognitive memory engine and Python SDK (hy-memory) for self-evolving LLM agents. It provides specialized memory pipelines across three task scenes: hierarchical long-term cognitive memory for Chat, two-layer fact and reusable-experience memory for Working, and version-evolution diff-chain tracking for Coding. Built on top of Hy Memory, MemHub is a local-first desktop and CLI product that unifies conversation history and coding traces from user-authorized AI applications into a single managed runtime and local data directory, enabling governed cross-application memory recall.

Key Features

• Dual-process cognitive memory architecture: personal memory is organized into an 8-layer hierarchy spanning raw dialogues, atomic facts, summaries, schemas, and prospective intentions, with conflict reconciliation and cross-domain schema induction.
• Three memory scenes selected through a scene router: chat for hierarchical memory L0-L7, working for two-layer session facts plus reusable experiences, and coding for the same two-layer memory plus a code version-evolution diff chain.
• Working memory records exactly one fact per session describing the task, approach, and result, alongside zero or more reusable experiences that must pass a value threshold.
• Coding memory reuses the working pipeline but records exact code coordinates instead of pasting code, stores data in isolated cv collections, and attaches every revision of touched code through a diff chain built with zero LLM calls.
• Three operating modes: lite for raw-only embedding writes and searches with no LLM calls, pro adding LLM extraction and reconciliation, and ultra adding System 2 schema induction and a cross-domain sweeper triggered by evolve().
• Python SDK with pluggable storage backends: ChromaDB, Qdrant, or FAISS vector stores, Kuzu or Neo4j graph stores, and local SQLite metadata, plus automatic scene routing, source isolation, and CRUD and evolution APIs.

Use Cases

• Building long-term personal memory for chat assistants, including preference recall, profile abstraction, summaries, and prospective intentions with expiry.
• Supporting productivity work such as documents, spreadsheets, research, financial analysis, content creation, and computer operation by remembering session facts and reusing proven approaches.
• Assisting software engineering tasks like coding, debugging, testing, builds, APIs/SDKs, scripts, and SQL, while tracking how each piece of code changed across versions.
• Unifying conversation history and coding traces from user-authorized AI applications such as Claude Code, Cursor, Codex, OpenCode, and Qwen Code into a single governed local runtime via MemHub.

Getting Started

• Install the SDK from PyPI with pip install hy-memory==2.0.2 for the core package including ChromaDB and Kuzu, or select extras such as [qdrant], [faiss], [graph], [mysql], [rerank], or [all]. Configuration requires only an LLM and an embedding endpoint, and any OpenAI-compatible

Deployment & Requirements

• An LLM endpoint and an embedding endpoint are required; any OpenAI-compatible service works, and the OpenAI defaults can be used with a single key.
• Vector stores supported are ChromaDB (default), Qdrant, and FAISS; graph stores used in ultra mode are Kuzu (default) and Neo4j.
• Working and Coding metadata is stored in local SQLite.
• Graph usage in pro mode is optional and controlled by MEMORY_ENABLE_GRAPH, which is off by default.

Before You Adopt

• License: Other. Review its terms before using, modifying, or distributing the project.
• The SDK depends on external LLM and embedding services, so an OpenAI-compatible endpoint and credentials must be supplied.
• Working and Coding scene memory only takes effect in pro or ultra mode and requires writes to carry a tool-call trace.