Skip to content
Back to search

claude-memory-ui

React SPA + FastAPI proxy UI for the claude-memory MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/first-it-consulting--claude-memory-ui/badge.svg)](/listings/first-it-consulting--claude-memory-ui)

HTML

<a href="/listings/first-it-consulting--claude-memory-ui"><img src="/api/listings/first-it-consulting--claude-memory-ui/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 180 lines
  1. # claude-memory-ui
  2. [![CI](https://github.com/first-it-consulting/claude-memory-ui/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/first-it-consulting/claude-memory-ui/actions/workflows/ci.yml)
  3. [![Release](https://img.shields.io/github/v/release/first-it-consulting/claude-memory-ui)](https://github.com/first-it-consulting/claude-memory-ui/releases)
  4. [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
  5. [![images](https://img.shields.io/badge/ghcr-linux%2Famd64%20%C2%B7%20arm64-brightgreen)](https://ghcr.io/first-it-consulting/claude-memory-ui)
  6. The browser face of **[claude-memory](https://github.com/first-it-consulting/claude-memory)** — the self-hosted, multi-user memory server for AI agents. Everything about the server, the quick start and the architecture lives in the [server README](https://github.com/first-it-consulting/claude-memory#readme); this repo is only the UI.
  7. It lets you browse, search and edit stored memories, inspect usage stats, review dedup job runs, and manage auto-tagging rules from a browser.
  8. The app is a **React + Vite TypeScript single-page application** served as static files by a lightweight **FastAPI proxy**. The proxy also transparently forwards `/api/*` requests (with bearer auth) to the claude-memory backend.
  9. ---
  10. ## Features
  11. - **Keycloak login** — the SPA signs users in via Keycloak (authorization code + PKCE); every API call carries the user's access token and the backend scopes it to their workspace.
  12. - **Multi-tenancy** — each user sees their own memories/sessions plus the admin-published shared space; admins get a workspace scope selector (mine / one tenant / all), the Jobs tab, a **Users** page for workspace management and a **Tokens** page that lists every user's API tokens (masked) for revocation.
  13. - **My tokens** — every user mints, lists and revokes their own API tokens (name, expiry 30/90/365 days, optional default harness; admins can opt a token into admin rights). The secret is shown once, the reveal dialog only closes via its button, and nothing is kept in browser storage. Revoking the shared `legacy-hooks` token needs a typed confirmation because it stops every unmigrated device.
  14. - **Memories** — list, search, filter by category/agent, edit content and tags, delete.
  15. - **Stats** — aggregate views (total memories, by agent, category and tag) with a visual stats bar.
  16. - **Jobs** — inspect past dedup job runs returned by claude-memory's `/api/jobs` (admin).
  17. - **Sessions** — session checkpoints (working memory) of Claude Code, Codex and pi sessions: filter by project/harness, read the checkpoint and the auto-captured notes, delete old sessions.
  18. - **Tag rules** — view and manage keyword→tag auto-classification rules (writes admin-only).
  19. - **Transparent proxy** — the FastAPI layer serves the SPA and proxies API calls to the backend, so there's a single port to expose. With Keycloak configured it forwards the browser's `Authorization` header untouched; without it (legacy single-tenant mode) it injects the shared `BEARER_TOKEN`.
  20. ## Screenshots
  21. From a demo workspace (invented data).
  22. ![Memories tab: invented project decisions and dead ends with category and tag chips, per-tenant workspace selector](docs/images/memories.png)
  23. *Memories - list, search, filter, edit; every entry shows category, tags and date.*
  24. ![Stats tab: totals, memories by category and agent, top tags](docs/images/stats.png)
  25. *Stats - totals, by category, by agent, top tags.*
  26. ![Sessions tab: two agent sessions with checkpoints, project and harness columns, goal line each](docs/images/sessions.png)
  27. *Sessions - per-agent-session checkpoints (working memory), filterable by project and harness.*
  28. ---
  29. ## Architecture
  30. ```
  31. Browser
  32. │
  33. ▼ http://localhost:8081
  34. ┌──────────────────────┐
  35. │ FastAPI proxy │ src/ui/app.py
  36. │ • serves SPA (dist/) │
  37. │ • proxies /api/* ────┼──────────────► claude-memory :8080
  38. │ • adds Bearer token │ (MCP server / REST API)
  39. └──────────┬────────────┘
  40. │ (dev only) npm run dev → Vite proxy /api → :8080
  41. ▼
  42. ┌──────────────────────┐
  43. │ React + Vite SPA │ ui/
  44. │ MUI · react-query │
  45. └──────────────────────┘
  46. ```
  47. In production the built SPA (`ui/dist`) is baked into the image and served by FastAPI; every `/api/*` request is proxied to `MCP_INTERNAL_URL` (default `http://claude-memory:8080`). With `KEYCLOAK_URL` set, the browser authenticates itself — the SPA does the Keycloak flow and the proxy forwards each caller's `Authorization` header untouched (the backend verifies the JWT, see claude-memory's `auth.py`), so the UI no longer needs oauth2-proxy in front for identification. Without `KEYCLOAK_URL` the proxy attaches the shared `BEARER_TOKEN` for every caller (legacy single-tenant mode; keep the UI behind SSO in that mode). Session checkpoints are reached through `/ui-api/sessions[/{id}]` (GET, DELETE only), because the ingress routes `/api/sessions` and `/api/hooks` straight to the server for the harness adapters. During local development Vite proxies `/api` to `http://localhost:8080`.
  48. The SPA reads its Keycloak settings at runtime from the proxy's `GET /ui-config.json` — realm changes need no rebuild. In the realm, give the UI client a web origin for the SPA host (redirect + CORS) and create the realm role `claude-memory-admin` to grant admins.
  49. ---
  50. ## Configuration
  51. Runtime settings are environment variables (see `src/ui/app.py`):
  52. | Variable | Default | Description |
  53. |---|---|---|
  54. | `MCP_INTERNAL_URL` | `http://claude-memory:8080` | Backend claude-memory API URL (used by the proxy). |
  55. | `BEARER_TOKEN` | *(empty)* | Legacy mode only: shared token injected when no Keycloak is configured. Match this to claude-memory's `BEARER_TOKEN`. |
  56. | `UI_PORT` | `8081` | Port the proxy/SPA listens on. |
  57. | `KEYCLOAK_URL` | *(empty)* | Keycloak base URL; setting it enables browser login and per-user token forwarding. |
  58. | `KEYCLOAK_REALM` | `master` | Realm the UI logs into (must match claude-memory's `OIDC_ISSUER` realm). |
  59. | `KEYCLOAK_CLIENT_ID` | `claude-memory-ui` | Public OIDC client; its id is the token audience the backend expects. |
  60. The dev server (`vite`) in `ui/vite.config.ts` proxies `/api` → `http://localhost:8080`.
  61. ---
  62. ## Build & run
  63. ### Requirements
  64. - Docker (with `buildx`) for image builds, **or** Node.js 20+ + Python 3.12+ for local development.
  65. ### Build the image (Docker Bake)
  66. ```bash
  67. # Single-platform to local daemon
  68. docker buildx bake -f docker-bake.hcl image-local
  69. # Multi-platform (amd64 + arm64) to a registry
  70. # REGISTRY defaults to ghcr.io/first-it-consulting; override to publish elsewhere
  71. REGISTRY=ghcr.io/<you> docker buildx bake -f docker-bake.hcl image-all --push
  72. ```
  73. ### Run the container
  74. ```bash
  75. docker run --rm -p 8081:8081 \
  76. -e BEARER_TOKEN=secret \
  77. -e MCP_INTERNAL_URL="http://claude-memory:8080" \
  78. claude-memory-ui:rolling
  79. # open http://localhost:8081
  80. ```
  81. ### Run locally (development)
  82. ```bash
  83. # 1. Build the SPA
  84. cd ui && npm ci && npm run build # output → ui/dist
  85. # 2. Serve + proxy
  86. pip install -r requirements-ui.txt
  87. export BEARER_TOKEN=secret MCP_INTERNAL_URL="http://localhost:8080"
  88. python src/ui/app.py # http://localhost:8081
  89. # …or use the Vite dev proxy (no build needed):
  90. cd ui && npm run dev # serves SPA, proxies /api → localhost:8080
  91. ```
  92. ---
  93. ## Project layout
  94. ```
  95. ├── Dockerfile # Stage 1: node builder (npm ci + vite build)
  96. # Stage 2: python slim (FastAPI proxy + static dist)
  97. ├── docker-bake.hcl # buildx bake targets (image / image-local / image-all)
  98. ├── requirements-ui.txt # Python deps: fastapi, uvicorn, httpx, aiofiles
  99. ├── src/
  100. │ └── ui/
  101. │ └── app.py # FastAPI: static file server + /api/* proxy
  102. └── ui/ # React SPA (Vite + TypeScript)
  103. ├── index.html
  104. ├── package.json # react, @mui/material, @tanstack/react-query, vite…
  105. ├── package-lock.json
  106. ├── tsconfig.json
  107. ├── vite.config.ts # dev proxy /api → localhost:8080
  108. └── src/
  109. ├── App.tsx, main.tsx
  110. ├── api/ # fetch wrappers: memories, jobs, tag-rules
  111. ├── components/ # MemoryCard, StatsBar
  112. ├── pages/ # Memories, Stats, Jobs, TagRules
  113. └── theme/ # MUI theme primitives
  114. ```
  115. ---
  116. ## API surface (proxied)
  117. The proxy forwards everything under `/api/*` to claude-memory. See the
  118. [claude-memory README](https://github.com/first-it-consulting/claude-memory#api-reference)
  119. for the full reference (`GET /api/memories`, `POST/PUT/PATCH/DELETE /api/memories/{id}`,
  120. `/api/stats`, `/api/tag-rules`, `/api/jobs`, export/import, …).
  121. ---
  122. ## Related projects
  123. - **[claude-memory](https://github.com/first-it-consulting/claude-memory)** — the MCP memory server this UI talks to.
  124. - **[containers-images](https://github.com/first-it-consulting/containers-images)** — the monorepo claude-memory-ui was originally part of (now extracted).
  125. ---
  126. ## Contributing and security
  127. Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
  128. Please report security issues privately as described in [SECURITY.md](SECURITY.md).
  129. ---
  130. ## License
  131. Licensed under the Apache License, Version 2.0 — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.