v1.0.2

What's Changed

• Powermem CLI Cases by @Ripcord55 in #369
• fix(cli): honor --env-file by loading POWERMEM_ENV_FILE in dotenv step by @Teingi in #371

Full Changelog: v1.0.1...v1.0.2

v1.0.1

What's Changed

• pyobvector dependencies by @Ripcord55 in #361
• Merge benchmark code by @Evenss in #362
• Native hybrid search case modification by @Ripcord55 in #363
• fix(api): register search router before memories by @Teingi in #367

Full Changelog: v1.0.0...v1.0.1

v1.0.0

Why We're Shipping the CLI and Dashboard

We believe that in the Agent era, the products that pull ahead will not be the ones with only a UI for humans to click. They will be the ones that deliver two layers at once: a layer where Agents can connect, execute, and orchestrate with low friction; and a layer where humans can understand the whole picture, form judgment, and consume results. The CLI is the operation surface for Agents and automation. The Dashboard is the cognition surface for people. Only when both exist does a product complete the shift from “software for humans” to “a system where humans and Agents work together.” That’s why, in v1.0.0, we’re making the CLI and the Memory Statistics and Analytics Dashboard first-class parts of PowerMem.

• CLI — the operation layer.
  Agents and scripts need a stable, scriptable interface: same config (.env), same storage as the SDK and API. The CLI (pmem) gives them exactly that—add/search/list/backup/restore from the terminal, in CI, or via an interactive shell (pmem shell)—without requiring a Python runtime or HTTP client in every context. It’s the low-friction surface for Agents to plug in and for you to automate bootstrap, migration, and recovery.

• Dashboard — the cognition layer.
  Humans need to see what’s in the system: how many memories, how they’re distributed by user/agent/type, and how healthy the system is. The dashboard is a web UI on top of the same HTTP API server, so operators and developers can build a mental model and make decisions without calling APIs or writing scripts. It’s optional to build and serve, but it’s the place where the “global view” lives.

Together, CLI and Dashboard close the loop: Agents operate; humans understand. That’s the dual-surface we’re shipping in v1.0.0.

---

New Features

1. CLI (pmem) — Command structure and config init

Command structure

All memory operations now live under the memory subcommand so the CLI has a clear hierarchy and room for other command groups (config, stats, manage, shell).

Command overview:

Group	Subcommands	Purpose
memory	add, search, get, update, delete, list, delete-all	CRUD and semantic search over memories.
config	show, validate, test, init	Inspect, validate, test, and create .env configuration.
stats	—	Print memory statistics (counts, distribution).
manage	backup, restore, cleanup, migrate	Backup/restore, Ebbinghaus cleanup, store migration.
shell	—	Interactive REPL with session defaults.

Invocation: After pip install powermem, use pmem or powermem-cli. Global options: --env-file PATH / -e, --json / -j, --verbose / -v, --install-completion SHELL, --version, --help.

Usage examples:

# Memory: add, search, list (with filters and pagination)
pmem memory add "User prefers dark mode" --user-id user123
pmem memory add "Meeting at 3pm Friday" -u user1 -a agent1 --no-infer
pmem memory search "user preferences" --user-id user123
pmem memory search "dark mode" -l 5 -t 0.3 -j
pmem memory list --user-id user123 -l 20 -o 0 --sort-by created_at --order desc
pmem memory get 123456789 --user-id user123
pmem memory update 123456789 "Updated content" -m '{"updated": true}'
pmem memory delete 123456789 --yes
pmem memory delete-all --user-id user123 --confirm

# Config: show, validate, test, and interactive init
pmem config show
pmem config show --section llm
pmem config validate -f .env.production
pmem config test -c database
pmem config init
pmem config init -f .env --test --component database

# Statistics and management
pmem stats
pmem stats -u user123 --detailed -j
pmem manage backup -o backup.json --user-id user123 -l 1000
pmem manage restore -i backup.json --skip-duplicates --dry-run
pmem manage restore -i backup.json -u new_user
pmem manage cleanup --dry-run
pmem manage cleanup --threshold 0.2 -u user123 --force

# Interactive shell (REPL with session defaults)
pmem shell
# Inside shell: set user user123; add "User likes tea"; search "preferences"; list --limit 10; exit

# Use a specific .env and JSON output
pmem -e .env.production --json stats
pmem --install-completion bash

pmem config init

Interactive wizard to create or update a .env file so you can bootstrap PowerMem without copying .env.example by hand.

• Modes: Quickstart (minimal prompts) or full custom (all sections).
• Options: --env-file PATH (target file), --dry-run (no write), --test / --no-test (run validation after writing), --component (e.g. database, llm, embedder, all) when using --test.

Examples:

pmem config init
pmem config init -f .env
pmem config init --test --component database

Full command reference: CLI Usage Guide.

---

2. Memory Statistics and Analytics Dashboard

A web-based dashboard for memory statistics and basic analytics, served by the same PowerMem HTTP API server. It gives a visual view of memory counts, distributions (e.g. by user, agent, type), and health-oriented metrics so you can monitor and debug without calling APIs or using the CLI.

When to use it: Inspecting how many memories you have, how they’re spread across users/agents, and whether the system is healthy. Useful for ops, support, and development.

How to run it:

1. Start the PowerMem HTTP API server (same as before):

   pip install powermem
   powermem-server --host 0.0.0.0 --port 8000

2. Open in a browser:

   http://localhost:8000/dashboard/
   

   (Replace host/port if you changed --host / --port.)

The dashboard uses the server’s existing API and configuration; no extra services are required. If you don’t build or copy the dashboard assets, the server still runs and only the /dashboard/ UI is unavailable.

---

3. Documentation

• CLI Usage Guide
  New guide at docs/guides/0012-cli_usage.md with:
  • Installation, invocation (pmem, powermem-cli), global options.
  • All memory, config, stats, manage, and shell commands with options and examples.
  • Interactive shell commands and shell completion (bash, zsh, fish, powershell).

---

Improvements and Fixes

HTTP API Server

• Server stop
  • When the PID file is stale (process already exited), server-stop now clears the port binding so a subsequent start does not fail with “port already in use” (#267).

OceanBase storage

• Hybrid search / pyobvector
  • where_clause is now passed in a shape compatible with pyobvector, fixing hybrid search when using OceanBase as the backend.

New Contributors

• @zty012 made their first contribution in #203
• @cr7258 made their first contribution in #212
• @NTLx made their first contribution in #208
• @knqiufan made their first contribution in #214
• @haosenwang1018 made their first contribution in #265

Full Changelog: v0.4.0...v1.0.0

v0.5.3

What's Changed

• fix lists bug by @Evenss in #268

Full Changelog: v0.5.2...v0.5.3

v0.5.2

What's Changed

• prompts: LANGUAGE DO NOT translate by @Teingi in #248
• Enhance memory listing functionality with pagination and sorting support by @Evenss in #246
• fix search bug by @Evenss in #253
• Enhance PGVectorConfig for flexible database connection settings by @Evenss in #257

Full Changelog: v0.5.1...v0.5.2

v0.5.1

What's Changed

1. Default role filters removed in UserMemory profile extraction:

• include_roles default changed from ["user"] to None
• exclude_roles default changed from ["assistant"] to None

2. Documentation updated to reflect the new defaults.

Impact

• Behavior change: Profile extraction will now, by default, not filter messages by role unless you explicitly pass include_roles and/or exclude_roles.
• This may change extracted profiles for users who relied on the previous implicit defaults (user-only input, assistant excluded).

Full Changelog: 0.5.0...v0.5.1

v0.5.0

PowerMem v0.5.0 Release Notes (2026-02-06)

Highlights

• Unified configuration governance across SDK/API Server (pydantic-settings based).
• OceanBase native hybrid search support.
• Enhanced Memory query experience with improved query handling and sorting support for memory list operations.
• User profiles now support custom native-language output.

What’s Changed

Configuration & Settings

• Unified configuration governance across the SDK and API Server based on pydantic-settings.

Retrieval & Storage

• Added OceanBase native hybrid search support.

SDK / API

• Enhanced Memory query handling.
• Added sorting support for memory list operations.

User Profile

• Added user profile support for custom native-language output.

Installation

pip install -U powermem==0.5.0

Full Changelog: v0.4.0...0.5.0

v0.4.0

PowerMem 0.4.0 Release Notes

Release Date: January 20, 2026

We're excited to announce the release of PowerMem 0.4.0! This version introduces significant enhancements to our retrieval capabilities with the addition of sparse vector support, enabling even more accurate and efficient memory search.

🎉 What's New

✨ Sparse Vector Support

PowerMem 0.4.0 introduces sparse vector support, a powerful enhancement to our hybrid retrieval system. Sparse vectors complement our existing dense vector and full-text search capabilities, providing a third dimension of semantic matching that significantly improves search accuracy, especially for keyword-rich queries.

Key Features:

• Enhanced Hybrid Retrieval: Combines dense vector search, full-text search, and sparse vector search for superior retrieval accuracy
• Automatic Sparse Vector Generation: Automatically generates sparse vectors when adding memories (no code changes required)
• Configurable Search Weights: Fine-tune the influence of each search method (vector, full-text, and sparse) through weight configuration

Database Requirements:

• OceanBase >= 4.5.0
• seekdb

Supported Providers:

• Qwen (text-embedding-v4)

🔧 Schema Upgrade & Migration Tools

To help users upgrade existing tables and migrate historical data, we've introduced comprehensive migration tools:

• Schema Upgrade Script: Automatically adds sparse vector support to existing OceanBase tables
• Data Migration Script: Migrates historical data to include sparse vectors with progress tracking and error handling

The migration tools support:

• Batch processing with configurable batch sizes
• Multi-threaded migration for improved performance
• Real-time progress monitoring
• Automatic skip of already migrated records

🧠 User Memory Query Rewriting

PowerMem 0.4.0 introduces intelligent query rewriting for UserMemory, which automatically enhances search queries based on user profiles to improve recall and accuracy.

Key Features:

• Automatic Query Enhancement: Rewrites vague or ambiguous queries using user profile information to make them more precise
• Profile-Based Context: Leverages extracted user profile content to fill in missing context in queries
• Graceful Fallback: Automatically falls back to the original query if profile is missing, query is too short, or rewrite fails
• Configurable: Enable/disable via configuration, with optional custom rewrite instructions
• Transparent Operation: No changes to search API - works seamlessly with existing UserMemory.search() calls

Configuration:

Enable query rewriting in your configuration:

config = {
    # ... other config
    "query_rewrite": {
        "enabled": True,
        # Optional: custom instructions for rewrite behavior
        # "prompt": "Rewrite queries to be specific and grounded in the user profile."
    }
}

Or via environment variables:

QUERY_REWRITE_ENABLED=true
# QUERY_REWRITE_PROMPT=  # Optional custom instructions

How It Works:

When UserMemory.search() is called with user_id and query rewrite is enabled:

1. Retrieves the user's profile from the profile store
2. Uses LLM to rewrite the query based on profile content
3. Executes search with the rewritten query for better results
4. Falls back to original query if any step fails

This feature significantly improves search recall by making queries more specific and context-aware based on what the system knows about each user.

📚 Documentation

Comprehensive documentation has been added for sparse vector functionality:

• Sparse Vector Guide: Complete guide on configuring and using sparse vectors
• Sparse Vector Example: Step-by-step tutorial with code examples
• Migration Guide: Detailed instructions for upgrading existing tables and migrating data

🚀 Getting Started

Enable Sparse Vector

Add the following to your .env file:

# Enable sparse vector
SPARSE_VECTOR_ENABLE=true

# Sparse vector embedding configuration
SPARSE_EMBEDDER_PROVIDER=qwen
SPARSE_EMBEDDER_API_KEY=your_api_key
SPARSE_EMBEDDER_MODEL=text-embedding-v4
SPARSE_EMBEDDER_DIMS=1536

For New Tables

Simply enable sparse vector in your configuration - no additional steps required:

from powermem import Memory, auto_config

config = auto_config()  # Ensure SPARSE_VECTOR_ENABLE=true
memory = Memory(config=config)

# Add memories (automatically generates sparse vectors)
memory.add("Your memory content", user_id="user123")

# Search (automatically uses sparse vector for hybrid search)
results = memory.search("query", user_id="user123")

For Existing Tables

Upgrade your existing tables using the migration tools:

from powermem import auto_config
from script import ScriptManager

config = auto_config()

# Step 1: Upgrade schema
ScriptManager.run('upgrade-sparse-vector', config)

# Step 2: Migrate historical data (optional but recommended)
from powermem import Memory
memory = Memory(config=config)
ScriptManager.run('migrate-sparse-vector', memory, batch_size=100, workers=3)

🔄 Migration from 0.3.x

For New Installations

No migration needed - simply install 0.4.0 and configure sparse vector if desired.

For Existing Installations

1. Upgrade PowerMem: pip install --upgrade powermem
2. Configure Sparse Vector: Add sparse vector configuration to your .env file
3. Upgrade Schema (if using OceanBase): Run the upgrade script to add sparse vector support
4. Migrate Data (optional): Run the migration script to generate sparse vectors for historical data

Note: Sparse vector is optional. Existing functionality continues to work without sparse vector enabled.

📊 Performance Improvements

With sparse vector support, PowerMem's hybrid retrieval system now provides:

• Better keyword matching: Sparse vectors excel at matching specific terms and keywords
• Improved semantic understanding: Combined with dense vectors, provides comprehensive semantic coverage
• Enhanced search accuracy: Three-way hybrid search (dense + sparse + full-text) delivers superior results

With user memory query rewriting:

• Improved query precision: Ambiguous queries are automatically clarified using user context
• Better recall: Profile-based query enhancement helps retrieve more relevant memories
• Personalized search: Each user's search queries are enhanced based on their unique profile

🐛 Bug Fixes & Improvements

• Improved error handling in vector store operations
• Enhanced logging for sparse vector operations
• Better validation of database version compatibility

📝 Breaking Changes

None. This release is backward compatible with 0.3.x.

🙏 Acknowledgments

Thank you to all contributors and users who provided feedback and helped improve PowerMem!

📖 Resources

• Full Documentation
• Sparse Vector Guide
• User Memory Guide - Includes query rewriting documentation
• Migration Guide
• GitHub Issues
• GitHub Discussions

---

Upgrade Now: pip install --upgrade powermem

Full Changelog: v0.3.1...v0.4.0

v0.3.1

Release v0.3.1

🎉 Overview

This PR releases PowerMem v0.3.1, which includes bug fixes, new LLM provider support, and documentation improvements.

✨ What's New

🐛 Bug Fixes

• Fixed user profile extraction bug (#172): Resolved an issue where user profile extraction was not working correctly in certain scenarios
• Fixed vector setting bug (#170): Corrected a bug related to vector database configuration that was causing issues in vector retrieval operations

🚀 New Features

• Added Zhipu AI (z.ai) integration support (#165): PowerMem now supports Zhipu AI as an LLM provider, expanding the options for users to choose their preferred AI service

📚 Documentation Improvements

• Added MCP and HTTP integration methods documentation (#164): Comprehensive documentation for integrating PowerMem via MCP Server and HTTP API Server
• Updated and fixed multiple documentation issues (#166, #84, #74, #61): Improved documentation accuracy and completeness across various sections

📋 Changes Summary

Category	Description
Bug Fixes	User profile extraction, vector setting configuration
New Features	Zhipu AI provider integration
Documentation	MCP/HTTP integration guides, various documentation updates

🔄 Migration Notes

No breaking changes in this release. Users can upgrade from v0.3.0 to v0.3.1 without any code changes.

📦 Release Information

• Version: 0.3.1
• Release Date: 2026-01-13
• Previous Version: 0.3.0

---

Related PRs

• docs: add MCP and HTTP integration methods documentation by @Teingi in #164
• docs: update docs by @Teingi in #166
• Added support for Zhipu AI (z.ai) integration by @wayyoungboy in #165
• fix vector setting bug by @Evenss in #170
• fix user profile extract bug by @Evenss in #172

Full Changelog: v0.3.0...v0.3.1

v0.3.0

PowerMem 0.3.0 Release Notes

Release Date: January 9, 2026

We're excited to announce the release of PowerMem 0.3.0! This version introduces a production-ready HTTP API Server and comprehensive Docker support, making PowerMem accessible to any application that supports HTTP calls, regardless of programming language.

🎉 Major Features

🌐 Production-Ready HTTP API Server

PowerMem now provides a fully-featured HTTP API Server built with FastAPI, exposing all core memory management capabilities through RESTful APIs. This enables seamless integration with any application that supports HTTP calls.

Key Features

• RESTful API Endpoints: Complete REST API for all memory operations

  • Memory management (create, read, update, delete, search)
  • Batch operations for efficient bulk processing
  • User profile management
  • Agent memory management and sharing
  • System health and status monitoring

• Security & Authentication

  • API Key authentication with configurable keys
  • Rate limiting to protect server resources (configurable per IP)
  • CORS support for web applications

• Production Features

  • Health check endpoint for monitoring
  • System status and metrics endpoints
  • Prometheus-compatible metrics format
  • Configurable worker processes for scalability

API Endpoints Overview

System Endpoints

• GET /api/v1/system/health - Health check (public endpoint)
• GET /api/v1/system/status - System status and configuration
• GET /api/v1/system/metrics - Prometheus metrics
• DELETE /api/v1/system/delete-all-memories - Bulk memory deletion

Memory Management Endpoints

• POST /api/v1/memories - Create memory (with intelligent extraction)
• POST /api/v1/memories/batch - Batch create memories
• GET /api/v1/memories - List memories with pagination
• GET /api/v1/memories/{memory_id} - Get specific memory
• PUT /api/v1/memories/{memory_id} - Update memory
• PUT /api/v1/memories/batch - Batch update memories
• DELETE /api/v1/memories/{memory_id} - Delete memory
• DELETE /api/v1/memories/batch - Bulk delete memories
• POST /api/v1/memories/search - Semantic search with hybrid retrieval

User Profile Endpoints

• POST /api/v1/users/{user_id}/profile - Create or update user profile
• GET /api/v1/users/{user_id}/profile - Get user profile
• DELETE /api/v1/users/{user_id}/profile - Delete user profile
• GET /api/v1/users/{user_id}/memories - Get all user memories
• DELETE /api/v1/users/{user_id}/memories - Delete all user memories

Agent Management Endpoints

• POST /api/v1/agents/{agent_id}/memories - Create agent memory
• GET /api/v1/agents/{agent_id}/memories - Get agent memories
• POST /api/v1/agents/{agent_id}/memories/share - Share memories between agents
• GET /api/v1/agents/{agent_id}/memories/share - Get shared memories

Quick Start

# Install PowerMem
pip install powermem

# Start the API server
powermem-server --host 0.0.0.0 --port 8000

# Access interactive API documentation
# Open http://localhost:8000/docs in your browser

🐳 Docker Support

Comprehensive Docker support for easy deployment and containerization, making PowerMem production-ready for containerized environments.

Features

• Dockerfile: Production-optimized multi-stage build

  • Minimal image size
  • Non-root user for security
  • Health check support
  • Configurable build arguments for mirror sources

• Docker Compose: Pre-configured setup for easy deployment

  • Automatic environment variable loading
  • Shared .env file support (SDK and Server)
  • Health checks and auto-restart
  • Logging configuration

• Production-Ready Configuration

  • Resource limits support
  • Health check endpoints
  • Structured logging with rotation
  • Security best practices

Quick Start with Docker

# Using Docker
docker run -d \
  --name powermem-server \
  -p 8000:8000 \
  -v $(pwd)/.env:/app/.env:ro \
  --env-file .env \
  oceanbase/powermem-server:latest

# Using Docker Compose (recommended)
docker-compose -f docker/docker-compose.yml up -d

📋 Configuration

The HTTP API Server shares the same configuration file (.env) as the PowerMem SDK, ensuring consistency between SDK and API server usage. New configuration sections have been added:

Server Configuration

# Server Settings
POWERMEM_SERVER_HOST=0.0.0.0
POWERMEM_SERVER_PORT=8000
POWERMEM_SERVER_WORKERS=4
POWERMEM_SERVER_RELOAD=false

# Authentication
POWERMEM_SERVER_AUTH_ENABLED=false
POWERMEM_SERVER_API_KEYS=key1,key2,key3

# Rate Limiting
POWERMEM_SERVER_RATE_LIMIT_ENABLED=true
POWERMEM_SERVER_RATE_LIMIT_PER_MINUTE=100

# Logging
POWERMEM_SERVER_LOG_FILE=server.log
POWERMEM_SERVER_LOG_LEVEL=INFO
POWERMEM_SERVER_LOG_FORMAT=text

# CORS
POWERMEM_SERVER_CORS_ENABLED=true
POWERMEM_SERVER_CORS_ORIGINS=*

🔄 Migration Guide

From 0.2.0 to 0.3.0

No breaking changes to the SDK! The HTTP API Server is an additional feature that doesn't affect existing SDK usage.

If you want to use the HTTP API Server:

1. Update PowerMem to 0.3.0:

   pip install --upgrade powermem

2. Add server configuration to your .env file (see Configuration section above)

3. Start the API server:

   powermem-server --host 0.0.0.0 --port 8000

Existing SDK code continues to work without any changes.

📚 Documentation

• API Server Documentation: Complete API reference with examples
• Docker Deployment Guide: Detailed Docker setup and deployment instructions
• Configuration Guide: Complete configuration options

📦 Dependencies

New Dependencies

• fastapi>=0.100.0 - Web framework for the API server
• uvicorn>=0.23.0 - ASGI server
• slowapi>=0.1.9 - Rate limiting middleware
• click>=8.0.0 - CLI framework

Updated Dependencies

• All existing dependencies remain compatible
• No breaking changes to existing dependencies

🙏 Acknowledgments

Thank you to all contributors and users who provided feedback and helped improve PowerMem!

---

Full Changelog: For a complete list of changes, see the GitHub Releases page.

Full Changelog: v0.2.1...v0.3.0