# DSH Math Notes Assistant (dsh-math-memory)

[English](README.md) · [简体中文](README.zh.md)

> A math-notes assistant that lives in Obsidian's right sidebar and remembers what you were working on between sessions.

Most chat assistants forget everything when a conversation ends. This one keeps your notes and a long-term memory inside your own vault, so a new session can pick up where the last one stopped. Everything stays on your machine.

## What it does

- **Remembers across sessions.** It keeps a profile, typed memory cards, idea memos and raw conversation evidence in `.deepseek/`, all as plain Markdown you can read and edit.
- **Finds things in one search.** `note_recall` searches your notes and all memory layers together, then reads the best hits before answering.
- **Lets you review and correct.** A memory panel shows what it knows; each card can be confirmed, marked wrong or archived, and replies link back to the cards they used.
- **Stays out of the way.** Notes stay in your vault, the service listens on localhost only, and the assistant has no shell, no web access and no delete tools.

## Current status

Version **0.8.3**, still a prototype. The "remember, find, correct" loop works end to end. What is still missing is the harder half: helping you build mathematical understanding — knowing where you are stuck, what to practise next, and how to reuse your own techniques. That is what 1.0 means. The current state and open work are kept in [docs/README.md](docs/README.md).

## Install

**A. From Obsidian (recommended).** Settings → Community plugins → Browse, search **DSH Math Notes Assistant**, then install and enable it. On first run the plugin finds DeepSeek Harness, sets up its configuration and vault templates, and starts the service.

**B. From the command line.**

```bash
npm install -g dsh-math-memory
dsh-math-memory install --vault "<path-to-your-vault>"
dsh --profile notes-assistant --port 3180
```

**C. Manually.** Download `main.js`, `manifest.json` and `styles.css` from the [latest release](https://github.com/maple110011/dsh-obsidian-math/releases) and copy them into `<vault>/.obsidian/plugins/dsh-math-assistant/`.

## Requirements

- Obsidian desktop and Node.js 22.5 or newer.
- DeepSeek Harness (`@deepseek-ai/dsh`, **requires ≥ 0.1.7-rc.2**) with a configured DeepSeek model.
- Default port 3180. The regular dsh web uses 3080; the two can run at the same time.

## Vault layout

```text
vault/
  AGENTS.md                     working agreement, loaded automatically
  .deepseek/
    memory/profile.md           who you are and how you like to work
    memory/notation.md          notation ledger
    memory/records/             memory cards
    memory/episodes/            raw conversation evidence
    memory/topics/              topic index
    inbox/                      idea memos
    capture-policy.md           what gets remembered automatically
```

## After install

Open the sidebar and start a conversation. At the start of each session the assistant reads `AGENTS.md` and the memory index. To see or correct what it remembers, open the memory panel; to change what is captured automatically, use the capture-policy row in the panel or the plugin settings.

## Project and development

- Current state and open work: [docs/README.md](docs/README.md)
- How the two components fit together: [ARCHITECTURE.md](ARCHITECTURE.md)
- Install and release details: [docs/installation.md](docs/installation.md), [docs/release.md](docs/release.md)
- Why decisions were made: [docs/changelog.md](docs/changelog.md)
- Before changing memory or retrieval: [docs/memory/README.md](docs/memory/README.md)
- The agent's tools: four note tools (`note_recall`, `note_strategy`, `note_create`, `note_links`) plus file read/write/search.

Development commands:

```bash
npm test          # syntax + 478 zero-token regression checks + 69 route-level checks + 8 real-dsh handshake checks + 24 loopback-proxy checks + installer e2e (drift detection)
npm run qa        # engine probe (no API cost)
node scripts/build-obsidian.mjs   # rebuild main.js after changing shared files
```

- Version: **0.8.3**

## Privacy

Everything runs locally: the service binds to 127.0.0.1, memory is Markdown inside your vault, and the session index never leaves the machine.

## License

MIT