Skip to content

Document the Web Dashboard and guide users through the frontend UI #959

Description

@longdafeng

Summary

PowerMem ships a Web Dashboard (served at /dashboard/ when running powermem-server), but end-user documentation for the frontend is minimal. Users currently only see brief mentions in the README and build instructions in the API server guide. There is no dedicated walkthrough explaining how to access, configure, and use the dashboard pages in day-to-day workflows.

Motivation

Since v1.0.0, the dashboard has become a first-class surface for inspecting and managing memories alongside the HTTP API server. Without clear documentation, new users may not discover key features (analytics, memory CRUD, user profiles, API key setup) or may struggle with common setup steps such as authentication and filtering by user_id / agent_id.

Current state

  • README mentions the dashboard path (/dashboard/) but does not describe its capabilities.
  • docs/api/0005-api_server.md covers how to build dashboard assets, not how to use them.
  • docs/development/overview.md includes developer build steps only.
  • The VS Code extension docs reference a separate extension dashboard panel, which can be confused with the web dashboard.

Proposed documentation

Add a user-facing guide (e.g. docs/guides/0013-dashboard.md or a section under the API server docs) that covers:

Getting started

  • How to start the server and open the dashboard (http://localhost:8848/dashboard/)
  • Docker / Compose access patterns
  • API key configuration (Settings page + server .env / POWERMEM_API_KEY)

Page-by-page walkthrough

  • Overview — stats cards, growth trends, system health, memory quality, filters (user_id, agent_id, time range)
  • Memories — search, list, view details, create/update/delete memories, pagination and filters
  • User Profile — viewing and understanding user profile data
  • Settings — API key management and connection troubleshooting

Operational guidance

  • Relationship between the web dashboard and the REST API / MCP / IDE extension
  • Common workflows (e.g. inspect memories after SDK integration, debug retrieval quality, monitor system health)
  • Troubleshooting (blank page, 401/unauthorized, stale data, rebuild steps when self-hosting from source)

Nice-to-have

  • Screenshots or short GIFs for each major page
  • Links from README, docs index, and API server guide to the new guide
  • Optional Chinese (README_CN.md) cross-link if we maintain localized docs

Acceptance criteria

  • A dedicated dashboard user guide exists in docs/
  • README and docs index link to the guide
  • Each dashboard page (Overview, Memories, User Profile, Settings) is documented with purpose and key actions
  • API key setup and common troubleshooting steps are included

Related code

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    Status
    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions