memoripo

Readme

# 🍃 memoripo

**A living workbench for the [DeepSeek Harness](https://github.com/deepseek-ai) Hindsight memory bank — grow, read, and use your agent's long-term memory from a persistent sidebar.**

*memoripo* = **memori**(es) + re**po** — your memory, as a browsable repository.

[中文说明](./README.zh.md)

---

## Why

DSH ships a powerful long-term memory engine (Hindsight), but its state lives in
a database and an ops log. memoripo turns that into a **visual workbench**: watch
memory grow day by day, see which memories actually get recalled, browse the
four knowledge layers, and manage pages — without leaving the chat UI.

## Features

### 🌱 Garden view (sidebar workbench)
- **Bank status at a glance** — daemon health, node/fact/link counts, four-layer split (world / experience / observation)
- **7-day growth curve** — horizontal per-day stacked bars so even quiet days stay legible
- **Timeline** — the latest background operations (ingest → consolidate → graph upkeep) with live status pills
- **Utilization heat** — which documents are actually being recalled (audit-driven), plus recent reads when tracking is on
- **Readable activity feed** — human labels instead of raw task types, capped with "show more"

### 🗂 Manage view (plugin-sized overlay)
- Full **knowledge-page browser**: card grid + folder tree, create/rename/move/delete, mental-model resynthesis
- **Page reader** with sticky TOC, markdown copy, raw-JSON copy
- **Operations panel** with retry / retry-all / clear-failed and a centered **detail modal** per task (progress stage & counters, full error text, copy JSON)
- Search, LLM & embedding config testing, template export/import — all migrated from the original manager under one roof

### ✨ Crafted details
- Unified top-light shadow system, gradient card faces, hover lift, press feedback, focus rings, slim scrollbars
- Fully localized (English / 简体中文), theme-variable aware (`--dsw-alias-*` with safe fallbacks)

### ⚙️ Zero-config daemon
- The plugin **auto-starts the local Hindsight daemon** on boot: a mount-time
  check plus a 45-second re-check respawn it if it dies mid-session, so no
  external start script is needed. The daemon's output is captured to
  `~/.hindsight/daemon.out.log` / `daemon.err.log` for forensics, and the
  status pill shows "connecting" while a spawn is in flight.

## Install

```bash
dsh plugin add github:Dayi-Z/memoripo
```

or from source:

```bash
git clone <this repo>
cd memoripo
pnpm install && pnpm run build
dsh plugin add ./ 
```

Then restart the web app. A 🍃 **Memoripo** entry appears in the main sidebar footer.

## Requirements

- DeepSeek Harness `>= 0.1.0-rc.6` with the web app enabled
- Node.js `^22.19 || >= 24`
- A Hindsight backend (daemon + PostgreSQL) — memoripo auto-starts the local
  daemon on boot (see "Zero-config daemon") and reads whatever bank DSH is
  configured to use

## Architecture (one minute)

```
src/
├── index.ts               # host plugin: /memoripo/* routes (status, growth, heat, pages…) + daemon supervisor mount
├── daemon.ts              # in-plugin daemon supervisor: 8888 check, offline spawn, 45s re-check, log capture
├── hindsight-routes.ts    # management endpoints (pages CRUD, operations, configs…)
└── client/
    ├── index.ts           # sidebar column + footer entry mount
    ├── Memoripo.tsx       # garden view (status, curve, timeline, heat, feed)
    └── …                  # manage view lives in src/hindsight-client/
```

The host registers read-only analytics routes on the DSH webserver; the client
bundle mounts a compact workbench into the conversation-frame sidebar and a
fuller management overlay reachable from the main sidebar footer. All UI text
goes through two flat locale dictionaries (`en`/`zh`) with `{n}` interpolation.

## Development

```bash
pnpm install
pnpm run typecheck   # server + client TS projects
pnpm run build       # lib/ (host) + client/client.js (browser bundle)
pnpm run check       # both
```

Restart the web app after rebuilding to load the new bundle.

## License

[MIT](./LICENSE)