v1.0.0

[Teingi]

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

   Or from source: make server-start, or Docker/Compose as in the API Server docs.

2. Build the dashboard and copy assets into the server so it can serve the UI:

   cd dashboard
   pnpm install
   pnpm build
   cd ..
   mkdir -p src/server/dashboard
   cp -r dashboard/dist/* src/server/dashboard/

   Then start (or restart) the server. If the src/server/dashboard/ directory exists and is populated, the server mounts the dashboard at /dashboard/.

3. 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” ([Bug]: When the PID expires, the server stop does not clear the port, resulting in subsequent server start failures and requests still being responded to by the old process #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 feat: Memory Statistics and Analytics Dashboard #203
• @cr7258 made their first contribution in feat(examples): Add Go client example for PowerMem HTTP API #212
• @NTLx made their first contribution in feat: Add pyseekdb support as storage backend (Issue #117) #208
• @knqiufan made their first contribution in feat: Add CLI scripts for PowerMem #214
• @haosenwang1018 made their first contribution in fix: replace bare except with specific exceptions in rerank modules #265

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

---

This discussion was created from the release v1.0.0.