Pick up where your last session left off. A Markdown-first personal workflow and cross-session memory setup for DeepSeek Harness (DSH).
Experimental · Unofficial. A small reference setup to copy and adapt, not a plugin or a production-ready framework.
flowchart TD
A["AGENTS.md<br/>Entry point"] --> R["RESPONSE_RULES.md<br/>Every session"]
A --> W["DSH_WORKFLOW.md<br/>Engineering tasks"]
A --> I["worklog / research INDEX<br/>Current state · read on demand"]
L["LEDGER.md<br/>Append-only source of truth"] -->|"derive current state"| I
L -.->|"trace sources"| P["Daily logs<br/>Provenance"]
V["memory-lint.py<br/>Structural checks"] -.-> L
V -.-> I
classDef entry fill:#e0e7ff,stroke:#6366f1,color:#1e1b4b
classDef memory fill:#dcfce7,stroke:#22c55e,color:#14532d
class A entry
class L,I memory
Arrows show responsibilities, not automatic execution. The agent reads the referenced files, appends events, and maintains the INDEX views; the linter checks their structure. The diagram describes this setup's user-level files, not every instruction source DSH loads.
Use this when you repeatedly explain unfinished work, rediscover a decision, or need to understand why a remembered conclusion changed. It separates working rules, current state, and the history behind that state using ordinary files you can inspect.
It does not make the model's answers correct or guarantee that it follows instructions. For occasional, unrelated chats, the bookkeeping may cost more than it saves. Start with the templates only if cross-session continuity is a real problem for you.
- Previously tested with
@deepseek-ai/dsh0.1.5-rc.2, read from the installedpackage.json. - Last recorded host verification: 2026-09-17. This documentation edit does not renew it.
- The linter requires Python 3 and uses only the standard library.
Instruction loading depends on the DSH version. Verify the
host assumptions against your own installation.
The templates use ~/.dsh; if you use a custom DSH_HOME, update their path references too.
Start in this repository's root. Check the fictional examples before touching your live setup:
python3 tools/memory-lint.py examplesExpected result: 0 errors, 0 warnings. This confirms the shipped examples are structurally valid; it does not install them or demonstrate cross-session recall.
To try the file layout in isolation:
trial_dir="$(mktemp -d "${TMPDIR:-/tmp}/dsh-threadmark.XXXXXX")"
cp -R examples/. "$trial_dir/"
mkdir -p "$trial_dir/tools"
cp tools/memory-lint.py "$trial_dir/tools/"
python3 "$trial_dir/tools/memory-lint.py"
printf 'Trial files: %s\n' "$trial_dir"This is a disposable file-layout trial, not a running DSH session. The copied instructions
still refer to ~/.dsh; do not point an agent at them without adapting those paths.
For live use, follow Setup and removal:
- Back up existing files and review the rule templates. Copy the seven files individually; merge with existing instructions or memory instead of overwriting them.
- Replace fictional ledger events and INDEX entries with your own confirmed information. Keep the Schema Contract and section structure. Do not invent a fact just to satisfy lint.
- Run the installed linter after adding the first real event and updating its INDEX entry. An empty Event Stream currently produces a fatal error; this is a tool limitation.
- Open a fresh DSH session and run the recall test. Inspect what the agent reads and compare its answer with the saved state.
No installer, database, or memory plugin is required. docs/ explains the setup; it is not
another set of runtime instructions to copy into DSH_HOME.
dsh-threadmark/
├── README.md
├── LICENSE
├── docs/
│ ├── architecture.md # responsibilities and host assumptions
│ ├── memory-schema.md # schema guide and actual lint coverage
│ ├── design-rationale.md # trade-offs and reasons for the design
│ └── setup-guide.md # installation, use, recall test, removal
├── examples/
│ ├── AGENTS.md
│ ├── RESPONSE_RULES.md
│ ├── DSH_WORKFLOW.md
│ ├── LEDGER.md
│ ├── worklog/INDEX.md
│ └── research/INDEX.md
├── tools/memory-lint.py
└── assets/ # reserved; the diagram above uses Mermaid
The examples contain fictional memory, not personal records. The rules are opinionated starting points: review them before use, especially their approval and Git conventions.
| File | Responsibility |
|---|---|
AGENTS.md |
User-level entry point; tells the agent when to read rules and memory. |
RESPONSE_RULES.md / DSH_WORKFLOW.md |
Discussion rules / engineering rules. Their full text lives in examples/. |
LEDGER.md |
Append-only record of durable facts, decisions, and lifecycle changes. |
worklog/INDEX.md / research/INDEX.md |
Current engineering / research state, maintained from the ledger by the agent. |
*/YYYY-MM-DD.md |
Supporting context for an event, when worth preserving. Not a general diary. |
tools/memory-lint.py |
Checks selected structural constraints after memory changes. |
The usual cycle is record a durable conclusion → update the relevant INDEX → run lint. When a conclusion changes, append a lifecycle event instead of rewriting its history. If nothing worth preserving happened, there is nothing to write.
INDEX entries retain ledger IDs so they can be checked against the authoritative record.
Next Actions is working state, not derivable from the ledger. Domain selection and the
wording of INDEX summaries still require judgement; there is no automatic rebuild tool.
The conflict policy and write criteria are declared in AGENTS.md.
These are illustrative fragments, not a complete installable ledger. A fictional event
under ## Event Stream in a file with Memory-Schema: 1 might be:
## W-260101-C3K7
Action: create
Time: 2026-01-01
Kind: goal
Grounding: user-statement
Provenance: none
Finish the parser migration; a failing encoding test is the current blocker.
Its current-state view in worklog/INDEX.md:
## Goals
- `W-260101-C3K7` — finish the parser migration; blocked by the encoding test.The ledger keeps the durable statement; the INDEX makes the active work easy to retrieve.
A fresh session can read the INDEX and identify the blocker without replaying every daily
note. Once the goal is complete, append a close event and remove its active INDEX entry.
See the Schema Contract for the full format.
- Agent-dependent execution. Loading rules and maintaining memory are not host-enforced. A well-written instruction can still be skipped.
- Partial validation. Lint does not judge truth, prove INDEX completeness, or enforce every lifecycle invariant. A passing run is not a correctness guarantee.
- Manual domain assignment. Schema v1 does not fully specify worklog/research membership. The agent must choose and review where each entity belongs.
- Unmeasured long-term cost. The ledger grows with history and INDEX files grow with active state. There is no demonstrated capacity limit or benchmarked context saving.
- Version-dependent loading. DSH internals can change; the recorded compatibility check is a historical observation, not a promise about future versions.
- Limited acceptance evidence. One cross-session recall test was previously reported; sustained use, concurrent writes, and larger workloads have not been validated.
To stop using this setup, first remove its instructions and references from the active
AGENTS.md files, then start a fresh session. For full removal, back up and remove only the
files or sections that belong to this setup; preserve unrelated instructions and data.
Do not delete ~/.dsh as an uninstall step. It can contain DSH sessions, attachments,
credentials, and other configuration.
Removal and recovery covers shared files, saved memory, project-level copies, and how to verify that the setup is no longer active.
- Architecture and host assumptions
- Memory schema and lint coverage
- Design rationale
- Setup, daily use, and removal
- Rule templates: discussion · engineering
MIT.