Timeline memory for DeepSeek Harness (dsh): an append-only log of facts, plus a summary pyramid the agent maintains by itself.
Ten thousand memories wake as 96 lines (≈7.3k tokens); any single memory is one seek away. Zero dependencies, plug and play.
Quick Install · Why "Pyramid" · Roadmap
Built with Fable 5
中文 | English
## Why "Pyramid"
Every time two facts fill up, the agent writes one line that stands for them; when two of *those* lines pair up, it writes one coarser line. Each layer holds half as many blocks as the one below — the shape is a tower:
```
[ #0-127 ] ← 1 line · covering all 128 facts
[ #0-63 ] [ #64-127 ] ← each line covers 64
[#0-31] [#32-63] [#64-95] [#96-127] ← each line covers 32
········································
#0 #1 #2 #3 ··················· #126 #127 ← the base: 128 verbatim facts
```
The wake-up view walks a **diagonal staircase down the tower**: last year is one line at the peak, last month sits behind a mid-layer brick, yesterday you read verbatim at the base. The base never moves — coarse bricks are only the map, and `memory_zoom` takes you down to the originals in two lines. So memory can grow tenfold and the view doesn't gain a line.
The shape takes its cue from Victor Taelin's [OptMem](https://github.com/VictorTaelin/OptMem). **The shape is the reference; everything else we worked out ourselves inside dsh** — see the features below.
## The slot it fills
| | Axis | What it remembers |
|---|---|---|
| `agent-instructions` (AGENTS.md chain) | Space | Which rules apply in which directory |
| Retrieval memory (RAG family) | Relevance | Things similar to the current question |
| **dsh-memory-pyramid** | **Time** | **What happened, in what order, and why it was decided that way** |
The three axes are orthogonal and stack cleanly. Officially only the space axis is occupied — **the time axis is entirely empty**. That's where this plugin lands.
The serial edition works today and runs **nothing in the background**. On the roadmap are two things you won't find elsewhere: **parallel background settlement** (memory-writing handed to a dedicated clone, costing your main thread zero attention) and a **memory dashboard** (humans get to see their own memory too — click a fact, jump back to the conversation that produced it).
## Features
**The pyramid mechanism**
- One fact per line, ≤280 bytes, append-only, never edited; summaries maintained by the agent as it writes — no background process, no timers
- Fixed reading budget: when everything fits, nothing is compressed; when it doesn't, older gets coarser — **never cut off**
- Bad summaries have a formal redraw channel (`memory_forget`), cascading to every coarser summary derived from them
**dsh-native adaptation (friction we solved ourselves)**
- Native dsh tools, not an external CLI — no shell permission needed
- **The injection channel was chosen on real API bills**: putting the view in the system prompt wrecks the prompt cache; moving it to the official dynamic runtime-context channel took whole-session hit rates from 40% to 91% (ledger below)
- **Session-range anchors**: every fact records which slice of conversation it was distilled from (`sessionId` + seq range) — dsh keeps a full event stream of every session, raw material that doesn't exist in OptMem's environment
- **Every integration channel was tested before we picked a seat**: the AGENTS.md channel (`agent-instructions`) ships root-flagged as disabled yet turns out alive in real sessions — but it's built for static, per-directory rules (cascading, never summarized); a memory view that changes on every write belongs in the official dynamic runtime-context channel
- Data-directory claiming / auto-migration / refusal to splice — better to not work than to write into someone else's directory
**Engineering properties**
- **Zero npm dependencies, zero native modules**; Node ≥ 19
- Windows / Linux / macOS / ARM64 (full green acceptance run on a postmarketOS phone)
- Multiple processes write the same memory **lock-free and correctly** — by removing a field, not adding a mutex
- Data lives in your workspace as plain text, diff-friendly; whether it goes into git is your choice
## Quick Install
Prerequisites: pnpm on PATH — dsh uses it to manage plugins on every platform (`npm install -g pnpm`; if the global directory isn't writable, `npm install -g pnpm --prefix ~/.local` and put `~/.local/bin` on PATH). Installing from source additionally needs git; the plugin itself has zero dependencies, no build step, Node.js ≥ 19.
One command:
```bash
dsh plugin --profile web add dsh-memory-pyramid
```
Installed means activated — the package declares `dsh.bundle`, so dsh adds it to the profile's layer stack automatically. **Not a single config file to edit.** The next new session wakes up with the Memory view. (You can also just ask your dsh agent to run the install for you.)
Uninstalling is one command too: `dsh plugin --profile web remove dsh-memory-pyramid`.
## Configuration
| Key | Default | Description |
|---|---|---|
| `namespace` | none | A shared-area name. If set, data lands in `
Higher layers hold fewer bricks, each covering more; the top row stands for everything. **The orange-outlined bricks are the ones in the context right now** — you can see at a glance what the model actually read at session start.
Zoom in and each brick carries the text of the stretch it represents:
A timeline underneath marks the span these memories cover; it pans and zooms, and the tower itself pans vertically when it grows taller than the card.
The knobs in the bottom-right take effect immediately: injected line count, bytes per fact, frozen vs. live.
The dashboard mounts through the front door dsh leaves open for third parties. Where there is no web UI (headless, for instance) it is simply absent, and memory itself keeps working.
### Click a memory, land on where it came from
Click a brick to read its text. Click a fact on the bottom row to walk back to its origin:
- **Came from a conversation** — jumps back to that conversation. Every fact stores a `sessionId` plus a range of sequence numbers, so what gets highlighted is **a complete turn**, not a single point.
- **Came from imported text** — opens that source in full.
When a fact has no recorded origin the button is greyed out. It never pretends to have one.
### Four sample libraries ship with the plugin
A tower of fifty facts and a tower of a few thousand are **completely different objects** — at fifty, the whole library fits in the context and not a single summary block is used; only in the thousands do the layers appear. But someone who just installed the plugin has zero facts.
So the package ships four ready-made libraries — **50 / 100 / 500 / 1000 facts** — switchable from the top-left of the dashboard the moment you install. No configuration, no download, and nothing is copied into your workspace. They are there in every workspace you open.
Switching to one shows **exactly what your own library shows**: the same tower, the same cards, the same memory view produced by the same algorithm. The difference speaks for itself — at 50 facts the view is 51 lines of verbatim originals and not one summary block is used; at 1000 it is 97 lines that open with coarse bricks like `#0-63`. **Both fit inside the same 96-line budget**, which is the claim "twenty times the memory, not one extra line to read at session start" stated as something you can look at.
All four are marked **⚗ synthetic**: the text is a public-domain novel, and the timestamps and heat values are generated, not anyone's real usage. That marking lives inside the library itself, so it travels wherever the library is copied and **can never be misread as a real ledger**.
The sample libraries are read-only — the dashboard does not write a single byte into them. And because they live inside the plugin's install directory rather than your workspace, the dashboard offers no unmount button for them. **Walking back to an origin does not work inside a sample library yet**: their conversation transcripts ship inside the pack but were never registered with dsh, so the click does nothing. In your own library it works normally.
There is also a 10,000-fact library, too large to ship in the package; it will be offered as a Releases download. Mounting any other library works the same way: **drop it into `