dsh-memento 0.4.0 → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ARCHITECTURE.md +177 -177
- package/CHANGELOG.md +104 -92
- package/README.es.md +163 -138
- package/README.hi.md +161 -136
- package/README.md +140 -137
- package/README.pt.md +164 -139
- package/README.zh.md +159 -156
- package/client/client.js +241 -241
- package/index.mjs +1739 -1730
- package/lib/constants.mjs +68 -68
- package/lib/store.mjs +717 -717
- package/package.json +153 -147
- package/types.d.ts +237 -237
package/README.pt.md
CHANGED
|
@@ -1,192 +1,217 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# dsh-memento
|
|
2
4
|
|
|
3
|
-
**Memória entre sessões limitada, em camadas,
|
|
5
|
+
**Memória entre sessões limitada, em camadas, com porta de aprovação e auditável para o DeepSeek Harness.**
|
|
6
|
+
|
|
7
|
+
*Uma costura tipada `ctx.memory`, uma porta de aprovação de escrita que nenhum caminho do modelo pode contornar e trilhas de auditoria reconstruíveis a partir do log de sessão.*
|
|
4
8
|
|
|
5
|
-
[](LICENSE)
|
|
10
|
+
[](https://github.com/topics/dsh-plugin)
|
|
11
|
+
[](#)
|
|
12
|
+
[](https://github.com/PerryLink/dsh-memento/actions)
|
|
13
|
+
[](https://github.com/PerryLink/dsh-memento/releases)
|
|
10
14
|
[](https://www.npmjs.com/package/dsh-memento)
|
|
11
15
|
[](https://www.npmjs.com/package/dsh-memento)
|
|
12
|
-
[](https://github.com/PerryLink/dsh-memento/actions/workflows/ci.yml)
|
|
13
16
|
|
|
14
|
-
[English](README.md) · [
|
|
17
|
+
[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
|
|
15
18
|
|
|
16
|
-
>
|
|
19
|
+
</div>
|
|
17
20
|
|
|
18
|
-
|
|
21
|
+
---
|
|
19
22
|
|
|
20
|
-
|
|
21
|
-
- **O portão não pode ser contornado.** Todo caminho de escrita (`add`/`replace`/`remove`/`seed`) é forçado pela cascata de aprovação **dentro do serviço**, não na camada da ferramenta. `writePolicy: ask | auto | off` é uma configuração que o modelo não pode ver nem alterar; uma postura `never` em nível de sessão ainda antecipa tudo. `replace`/`remove`/`consolidate` carregam o texto completo das entradas que vão mudar no payload de aprovação — o que você aprova é o que você vê, e uma escrita negada ainda registra uma linha de auditoria `*-denied`.
|
|
22
|
-
- **Visível ao modelo ⟺ registrado em log.** O snapshot injetado cai literalmente em `request/header.system`; toda escrita é reconstruível a partir de `approval/asked` (carga completa) + `approval/decided` (resultado) + a própria tabela de auditoria do plugin.
|
|
23
|
-
- **Limitado e honesto.** Orçamentos rígidos de caracteres por trilha/camada (padrão usuário 2000 / agente 4000). Um armazenamento cheio **falha com um erro estruturado** (uso + limite) — o modelo consolida e tenta novamente. Nunca truncado, nunca auto-compactado.
|
|
23
|
+
## Compatibility
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
| Surface | Status |
|
|
26
|
+
|---|---|
|
|
27
|
+
| Harness | DeepSeek Harness `0.1.0-rc.6` |
|
|
28
|
+
| Node | `^22.19.0 || >=24.0.0` |
|
|
29
|
+
| Platforms | Windows / macOS / Linux (somente host; sem código nativo, sem rede) |
|
|
30
|
+
| Model | Qualquer |
|
|
26
31
|
|
|
27
|
-
|
|
28
|
-
# requer Node ^22.19 || >=24 e DSH 0.1.0-rc.6
|
|
29
|
-
dsh plugin --profile web add dsh-memento # ou ./dsh-memento / um tarball / uma URL do GitHub
|
|
30
|
-
dsh --profile web --dump-config # espere uma camada "# == dsh-memento", sem FAILED na inicialização
|
|
31
|
-
```
|
|
32
|
+
## What you get
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
O `dsh-memento` é uma costura de capacidade, não outro armazém: um serviço tipado `ctx.memory`, um provedor SQLite local (`node:sqlite`, WAL, `0600`, em `$DSH_HOME/dsh-memento/memory.db`) e seus consumidores — a ferramenta `memory` e um snapshot congelado injetado no prompt do sistema.
|
|
34
35
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
-
|
|
38
|
-
config:
|
|
39
|
-
writePolicy: ask # ask (padrão) | auto | off — invisível ao modelo
|
|
40
|
-
budgets:
|
|
41
|
-
user: { userGlobal: 4000, workspace: 2000 } # memória com muito chinês: aumente + anote o porquê
|
|
42
|
-
agent: { userGlobal: 4000, workspace: 4000 }
|
|
43
|
-
```
|
|
36
|
+
- **A porta não pode ser contornada.** Todo caminho de escrita (`add` / `replace` / `remove` / `seed`) passa pela cascata de aprovação dentro do serviço, não na camada de ferramentas. `writePolicy: ask | auto | off` é configuração invisível para o modelo; `replace` / `remove` / `consolidate` carregam o texto completo das entradas que alteram no payload de aprovação, e uma escrita negada ainda gera uma linha de auditoria `*-denied`.
|
|
37
|
+
- **Visível para o modelo ⟺ registrado.** O snapshot injetado chega textualmente a `request/header.system`; toda escrita é reconstruível a partir de `approval/asked` + `approval/decided` + a própria tabela de auditoria do plugin.
|
|
38
|
+
- **Limitado e honesto.** Orçamentos rígidos de caracteres por trilha e por camada (padrão usuário 2000 / agente 4000). Um armazém cheio falha com erro estruturado (uso + limite) — nunca trunca, nunca compacta automaticamente.
|
|
44
39
|
|
|
45
|
-
|
|
40
|
+
Duas trilhas × duas camadas × chave por agente: uma trilha `user` (fatos sobre o usuário) e uma trilha `agent` (fatos de ambiente e convenções), cada uma dividida em camadas `user-global` e `workspace`, isoladas por `agentPreset`. O snapshot é congelado uma vez por sessão na primeira montagem do prompt e nunca muda no meio da sessão.
|
|
46
41
|
|
|
47
|
-
|
|
48
|
-
| --- | --- | --- |
|
|
49
|
-
| 🧩 Service Definition | `ctx.memory` — `add` / `replace` / `remove` / `query` / `seed` / `budgets()` | Serviço tipado, declarado por merge; os métodos de escrita impõem o portão internamente |
|
|
50
|
-
| 🧬 Registro de adaptadores | `ctx.memoryAdapters` — `register` / `list` / `adapt` / `export` | Plugins de memória de terceiros adaptam o próprio armazenamento ao protocolo; adaptadores de referência para mem0, `memory.md` do Hermes e `CLAUDE.md` já vêm embutidos |
|
|
51
|
-
| 💾 Provider | `lib/store.mjs` — `node:sqlite` arquivo único (`$DSH_HOME/dsh-memento/memory.db`, WAL) | Zero dependências, zero rede; tabelas de entrada + auditoria; correspondência por substring única |
|
|
52
|
-
| 🛠 Consumers | ferramenta `memory` · injeção de snapshot congelado (seção de system-prompt, ordem `-50`) · ferramenta `memory_recall` · comando `/memory` · painel Web somente leitura | Escritas/leituras voltadas ao modelo, snapshot congelado com cabeçalho de orçamento, recuperação em duas partes, comando do usuário, gaveta do navegador |
|
|
42
|
+
## Quick start
|
|
53
43
|
|
|
54
|
-
|
|
44
|
+
```sh
|
|
45
|
+
# 1. install the bundle into your profile
|
|
46
|
+
dsh plugin --profile web add "github:PerryLink/dsh-memento#main"
|
|
55
47
|
|
|
56
|
-
|
|
48
|
+
# or from npm (published releases)
|
|
49
|
+
dsh plugin --profile web add dsh-memento
|
|
57
50
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
add/replace/remove/query per-session freeze, budget-headed
|
|
61
|
-
│ writes (agent+callId) │ reads (sync, session cwd)
|
|
62
|
-
▼ ▼
|
|
63
|
-
Service Definition: ctx.memory — budgets/add/replace/remove/query/seed
|
|
64
|
-
every write: budget precheck → ctx.approval.request (approval waterfall) → budget recheck → persist → audit
|
|
65
|
-
│
|
|
66
|
-
▼
|
|
67
|
-
Provider: lib/store.mjs — node:sqlite (WAL, 0600), entries + audit tables, unique-substring match
|
|
51
|
+
# 2. restart and verify the row
|
|
52
|
+
dsh --profile web --dump-config | grep -A3 'id: memento'
|
|
68
53
|
```
|
|
69
54
|
|
|
70
|
-
##
|
|
55
|
+
## Install & uninstall
|
|
56
|
+
|
|
57
|
+
- **canal git** (último `main`): `dsh plugin --profile web add git+https://github.com/PerryLink/dsh-memento.git`.
|
|
58
|
+
- **canal npm** (versões publicadas): `dsh plugin --profile web add dsh-memento`.
|
|
59
|
+
- **canal tarball**: `npm pack` neste repo, depois `dsh plugin --profile web add ./dsh-memento-<version>.tgz`.
|
|
60
|
+
- **desinstalar**: `dsh plugin --profile web remove dsh-memento` (o banco de memória e os logs de sessão são mantidos).
|
|
61
|
+
|
|
62
|
+
## Configuration
|
|
63
|
+
|
|
64
|
+
Todos os parâmetros são campos Schemastery `Config` (alteráveis pelo cordis.yml). Valores inválidos falham ruidosamente ao carregar. Sobrescreva na linha `memento`.
|
|
65
|
+
|
|
66
|
+
| Key | Default | Meaning |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| `enabled` | `true` | Interruptor mestre; `false` remove serviço, ferramentas, snapshot, comando, painel e answerer |
|
|
69
|
+
| `dbPath` | `''` → `$DSH_HOME/dsh-memento/memory.db` | Absoluto, ou relativo a `$DSH_HOME` (no Windows cai para `~/.dsh`) |
|
|
70
|
+
| `budgets.user.userGlobal` | `2000` | Orçamento rígido de caracteres da camada user-global da trilha user |
|
|
71
|
+
| `budgets.user.workspace` | `2000` | Orçamento rígido de caracteres da camada workspace da trilha user |
|
|
72
|
+
| `budgets.agent.userGlobal` | `4000` | Orçamento rígido de caracteres da camada user-global da trilha agent |
|
|
73
|
+
| `budgets.agent.workspace` | `4000` | Orçamento rígido de caracteres da camada workspace da trilha agent |
|
|
74
|
+
| `writePolicy` | `'ask'` | Política de escrita padrão: `ask` / `auto` / `off` (invisível para o modelo) |
|
|
75
|
+
| `writePolicies` | `{}` | Sobrescritas por trilha/escopo ou por origem (ex.: `user/workspace`, `source:claude`) |
|
|
76
|
+
| `language` | `'en'` | Idioma do texto visível e da saída do comando: `en` / `zh` |
|
|
77
|
+
| `snapshotOrder` | `-50` | Ordem da seção de snapshot (após a identidade do harness, antes de persona) |
|
|
78
|
+
| `maxEntriesPerQuery` | `20` | Limite de resultados por consulta (limite rígido 1000) |
|
|
79
|
+
| `commandListLimit` | `50` | Entradas exibidas por `/memory list` / `query` |
|
|
80
|
+
| `commandAuditLimit` | `10` | Linhas de auditoria exibidas por `/memory audit` |
|
|
81
|
+
| `recall.historyLimitDefault` | `8` | Sessões escaneadas pelo `memory_recall` por padrão |
|
|
82
|
+
| `recall.snippetCap` | `5` | Fragmentos por sessão no `memory_recall` |
|
|
83
|
+
| `recall.snippetChars` | `300` | Caracteres de fragmento no `memory_recall` |
|
|
84
|
+
| `recall.windowDays` | `30` | Janela de recência em dias do `memory_recall` |
|
|
85
|
+
| `panelEntriesLimit` | `200` | Tamanho de página de entradas do painel web |
|
|
86
|
+
| `panelAuditLimit` | `20` | Linhas de auditoria do painel web por padrão |
|
|
87
|
+
| `auditRetentionDays` | `0` | Retenção de auditoria (0 = manter para sempre) |
|
|
88
|
+
| `proposals.enabled` | `true` | Capturar automaticamente uma proposta de memória após cada compactação bem-sucedida |
|
|
89
|
+
| `proposals.maxChars` | `2000` | Limite de caracteres da proposta |
|
|
90
|
+
| `proposals.maxPending` | `8` | Limite de propostas pendentes |
|
|
91
|
+
|
|
92
|
+
## Tools & surfaces
|
|
93
|
+
|
|
94
|
+
| Surface | Kind | Notes |
|
|
95
|
+
|---|---|---|
|
|
96
|
+
| `memory` | tool | add/replace/remove/consolidate/query com orientação Save/Skip; escritas passam pela porta de aprovação |
|
|
97
|
+
| `memory_recall` | tool | Correspondências limitadas de memória mais correspondências recentes do histórico de sessão |
|
|
98
|
+
| `/memory` | command | `list` · `query` · `add` · `remove` · `consolidate` · `proposals` · `budgets` · `audit` · `export` · `import <path>` · `adapters` |
|
|
99
|
+
| web panel | client drawer | Somente leitura: navegar entradas, buscar, barras de orçamento, cauda de auditoria |
|
|
100
|
+
|
|
101
|
+
## How it's different
|
|
71
102
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
dsh
|
|
75
|
-
dsh
|
|
76
|
-
dsh
|
|
77
|
-
|
|
103
|
+
| Plugin | O que é | A diferença do dsh-memento |
|
|
104
|
+
|---|---|---|
|
|
105
|
+
| dsh-memory-evolve | armazém de memória / laços de evolução | costura de serviço tipada, porta de aprovação e auditoria de log de sessão; sem ambição de armazém |
|
|
106
|
+
| dsh-mnemon | auxiliar de armazenamento de memória | protocolo + porta + auditoria, não outro armazém |
|
|
107
|
+
| dsh-kb-sieve | peneiramento de base de conhecimento | sem engenharia de recuperação: busca por substring em corpus pequeno, recall entre sessões via `session_search`/`sessionQuery` |
|
|
108
|
+
| dsh-tdai-memory | ferramentas de memória dirigidas por tarefa | orçamentos são por track×camada e aplicados no serviço, não no melhor esforço |
|
|
109
|
+
| claude-bridge | ponte do Claude Code | nativo do DSH; uma futura rota `seed(source:'claude')` deixa uma ponte alimentar o mesmo armazém |
|
|
110
|
+
| dsh-external/Recall | memória de agente externa | local primeiro, zero rede, usa a própria costura de aprovação do DSH |
|
|
111
|
+
| Official MCP memory examples | a posição declarada do DSH de "memória = MCP externo" | o complemento **nativo de primeira parte**: mesmo objetivo, sem servidor externo; ambos coexistem |
|
|
78
112
|
|
|
79
|
-
|
|
113
|
+
O nome é **`dsh-memento`** (publicado no npm e no GitHub). Não `dsh-recall` (confundível com dsh-external/Recall), não o nome legado excluído `dsh-memory`.
|
|
80
114
|
|
|
81
|
-
##
|
|
115
|
+
## dsh-memory-protocol v1
|
|
82
116
|
|
|
83
|
-
|
|
117
|
+
O `dsh-memento` é o ensaio comunitário do protocolo de memória DSH — uma forma candidata para uma costura oficial `ctx.memory`. O protocolo normaliza a costura deste plugin em um contrato entre plugins:
|
|
84
118
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
| `budgets.agent.userGlobal` / `budgets.agent.workspace` | `4000` / `4000` | orçamento rígido de caracteres por camada da trilha agent |
|
|
91
|
-
| `writePolicy` | `'ask'` | `'ask'` = aprovação do usuário; `'auto'` = permite passar (fonte da aprovação registrada); `'off'` = rejeita. Invisível ao modelo |
|
|
92
|
-
| `writePolicies` | `{}` | substituições por trilha/camada ou por fonte: chaves `user/workspace`, `agent/user-global`, `source:claude`, … → `ask`/`auto`/`off`; sem correspondência cai para `writePolicy` |
|
|
93
|
-
| `language` | `'en'` | idioma do texto visível ao modelo e da saída do comando: `'en'` (padrão) ou `'zh'` — descrições de ferramentas, snapshot congelado, comando `/memory` e painel web o seguem |
|
|
94
|
-
| `snapshotOrder` | `-50` | ordem da seção do snapshot: depois da identidade do harness (`-100`), antes da persona (`0`) |
|
|
95
|
-
| `maxEntriesPerQuery` | `20` | limite padrão de resultados por consulta (`limit` explícito permitido, teto rígido 1000) |
|
|
96
|
-
| `commandListLimit` | `50` | entradas exibidas por comando `/memory list` / `query` |
|
|
97
|
-
| `commandAuditLimit` | `10` | linhas de auditoria exibidas por comando `/memory audit` |
|
|
98
|
-
| `recall.historyLimitDefault` / `recall.snippetCap` / `recall.snippetChars` / `recall.windowDays` | `8` / `5` / `300` / `30` | padrões de histórico do `memory_recall`: sessões escaneadas, trechos por sessão, caracteres por trecho, janela em dias |
|
|
99
|
-
| `panelEntriesLimit` | `200` | tamanho da página de entradas do painel web (e teto) |
|
|
100
|
-
| `panelAuditLimit` | `20` | linhas de auditoria do painel web por padrão (teto 200) |
|
|
101
|
-
| `auditRetentionDays` | `0` | retenção de auditoria: 0 = para sempre, >0 = poda ao abrir a loja |
|
|
102
|
-
| `proposals.enabled` / `proposals.maxChars` / `proposals.maxPending` | `true` / `2000` / `8` | auto-captura: proposta de memória pendente após cada compactação bem-sucedida (truncada, uma por sessão); desativar ou ajustar limites |
|
|
119
|
+
- **Entry spec** — duas trilhas × duas camadas × chave por agente, mais `tags` curtos (≤16 × ≤32 caracteres) e um `version` por entrada que incrementa a cada `replace`.
|
|
120
|
+
- **Write semantics** — escritas condicionais idempotentes por substring única; payloads de aprovar-o-que-se-vê (`replace` / `remove` / `consolidate` carregam o texto completo que alteram).
|
|
121
|
+
- **Audit contract** — toda escrita reconstruível a partir de `approval/asked` + `approval/decided` + o livro-razão do provedor.
|
|
122
|
+
- **Budget model** — semântica `BUDGET_EXCEEDED` / `AMBIGUOUS_MATCH`.
|
|
123
|
+
- **Schema versioning** — regras de migração com verificações de versão ruidosas.
|
|
103
124
|
|
|
104
|
-
|
|
125
|
+
- **Spec** — [docs/protocol-v1.md](docs/protocol-v1.md) (中文: [protocol-v1.zh.md](docs/protocol-v1.zh.md)); JSON Schema normativo em [docs/schemas/dsh-memory-protocol-v1.schema.json](docs/schemas/dsh-memory-protocol-v1.schema.json).
|
|
105
126
|
|
|
106
|
-
|
|
107
|
-
- **`memory_recall`** — recuperação em duas partes: correspondências de memória limitadas **mais** correspondências recentes do histórico da sessão via `ctx.sessionQuery` (degrada graciosamente para somente memória onde o serviço está ausente).
|
|
108
|
-
- **`/memory`** — comando acionado pelo usuário (não um turno do modelo): `list` · `query <word>` · `add [--track=user|agent] [--scope=user-global|workspace] <text>` · `remove [flags] <substring>` · `consolidate [flags] <substring...> => <text>` · `proposals [approve|dismiss <id>]` · `budgets` · `audit` · `export [--adapter=<id>]` · `import <path> [--adapter=<id>]` · `adapters`. Escritas por comando passam pela mesma cascata + política; a auditoria cai na tabela de auditoria do plugin + `command/done`. `export` é somente leitura e despeja todas as entradas + orçamentos como um documento JSON; `import` o restaura (caminho de arquivo ou JSON inline, uma única aprovação, orçamentos pré-verificados) — um ciclo completo de backup/migração. Os verbos de adaptador convertem formatos de memória externos: `import --adapter=mem0 <facts.json>` alimenta fatos pelo `seed` com portão de aprovação; `export --adapter=<id>` imprime uma conversão somente leitura. Entradas importadas ganham ids e carimbos de tempo novos; propostas, linhas de auditoria e contadores de recuperação não são migrados.
|
|
109
|
-
- **Propostas auto-capturadas** — após uma compactação de sessão bem-sucedida, o resumo vira uma proposta de memória pendente (`agent/workspace`); aprovar a escreve pelo portão de aprovação, descartar a remove. Propostas pendentes aparecem no snapshot congelado e no painel.
|
|
110
|
-
- **Painel Web** — gaveta `dsh.client` sem build: navegue pelas entradas por trilha/camada, pesquise, veja barras de orçamento e o fim da auditoria. Somente leitura por design: escritas e aprovação acontecem pela ferramenta `memory` e pela UI de aprovação embutida.
|
|
127
|
+
**Registro de adaptadores** — `ctx.memoryAdapters` (`register` / `list` / `adapt` / `export`) permite que plugins de memória de terceiros falem o protocolo registrando um conversor de dados puro (`register()` reversível; a importação usa o `seed` com porta de aprovação, a exportação é somente leitura). Integração: [docs/adapters-guide.md](docs/adapters-guide.md) (中文: [adapters-guide.zh.md](docs/adapters-guide.zh.md)).
|
|
111
128
|
|
|
112
|
-
|
|
129
|
+
| Built-in adapter | External format | Notes |
|
|
130
|
+
|---|---|---|
|
|
131
|
+
| `mem0` | coleções de fatos mem0 (`{facts: [{memory, metadata?}]}`) | `metadata.category` / `metadata.tags` viram tags; arrays `messages` crus são rejeitados — adaptadores convertem, nunca extraem |
|
|
132
|
+
| `hermes-memory-md` | `memory.md` do Hermes (`## section` + marcadores) | nomes de seção viram tags; prosa sem marcadores falha ruidosamente |
|
|
133
|
+
| `claude-code-memory-md` | markdown estilo `CLAUDE.md` (títulos, marcadores, parágrafos) | marcadores e parágrafos viram entradas; nomes de seção viram tags |
|
|
113
134
|
|
|
114
|
-
|
|
135
|
+
**Suíte de conformidade** — [test/protocol-conformance/](test/protocol-conformance/README.md): um conjunto de casos distribuível que qualquer provedor que reivindique compatibilidade executa (`node test/protocol-conformance/run.mjs --provider ./your-factory.mjs`); o CI deste repo o executa contra seu próprio provedor como referência dourada (`npm run test:conformance`).
|
|
115
136
|
|
|
116
|
-
|
|
117
|
-
| --- | --- | --- |
|
|
118
|
-
| **Claude Code** — `CLAUDE.md` | **arquivos de memória em texto puro** hierárquicos (nível usuário → nível projeto), legíveis e editáveis por humanos, e mesclados automaticamente a cada sessão — memória que você mesmo pode ler e corrigir | entradas em texto puro; camadas `user-global` / `workspace` mescladas por sessão; um armazenamento que você pode navegar, `export`ar e auditar — transparência como recurso |
|
|
119
|
-
| **Codex** — `AGENTS.md` | **instruções com escopo por diretório** autodescobertas e injetadas sem fricção do modelo — localidade vale mais que volume; nenhuma chamada de ferramenta é necessária para "carregar" memória | camada `workspace` vinculada ao cwd da sessão (insensível a maiúsculas no Windows); o snapshot congelado é injetado automaticamente no início da sessão |
|
|
120
|
-
| **Hermes** — `memory.md` | **gravações de memória proativas** (salvar/atualizar/apagar) e, na [issue #48181](https://github.com/NousResearch/hermes-agent/issues/48181), a lição de segurança de que um portão imposto apenas na camada de ferramentas é contornável por injeção tardia de ferramentas — imponha-o onde todas as rotas de escrita convergem | a ferramenta `memory` com orientação explícita de Salvar/Pular + propostas de auto-captura com portão de aprovação; o portão de aprovação vive **dentro** dos métodos de escrita de `ctx.memory`, não na camada de ferramentas |
|
|
137
|
+
- **Upstream proposal** — [docs/upstream-proposal.md](docs/upstream-proposal.md) (中文: [upstream-proposal.zh.md](docs/upstream-proposal.zh.md)): por que a costura oficial `ctx.memory` deveria adotar o protocolo, as diferenças e o caminho de migração.
|
|
121
138
|
|
|
122
|
-
|
|
139
|
+
## Permissions & data
|
|
123
140
|
|
|
124
|
-
|
|
141
|
+
- **Permissions**: o manifesto de workshop declara `harness:tool`, `filesystem:read`, `filesystem:write` e `network:none` / `subprocess:none` / `shell:none` / `python:none` / `credentials:none`. A aprovação de escrita usa a costura oficial de aprovação.
|
|
142
|
+
- **Data**: banco de dados SQLite local (`0600`), zero rede, zero credenciais.
|
|
143
|
+
- **Session log**: a completude da auditoria vem do par de aprovação (`approval/asked` + `approval/decided`) mais a tabela de auditoria do plugin.
|
|
125
144
|
|
|
126
|
-
##
|
|
145
|
+
## Security boundaries
|
|
127
146
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
| dsh-kb-sieve | peneiramento de base de conhecimento | sem engenharia de recuperação: busca por substring em corpus pequeno, recuperação entre sessões via `session_search`/`sessionQuery` |
|
|
133
|
-
| dsh-tdai-memory | ferramentas de memória orientadas a tarefas | orçamentos são por trilha×camada e impostos no serviço, não best-effort |
|
|
134
|
-
| claude-bridge | ponte para o Claude Code | nativo de DSH; um futuro caminho `seed(source:'claude')` permite que uma ponte alimente o mesmo armazenamento |
|
|
135
|
-
| dsh-external/Recall | memória de agente externo | local em primeiro lugar, zero rede, usa a própria emenda de aprovação do DSH |
|
|
136
|
-
| Exemplos oficiais de memória MCP | a posição declarada do DSH de "memória = MCP externo" | o complemento **nativo de primeira parte**: mesmo objetivo, sem servidor externo; ambos coexistem |
|
|
147
|
+
- **Somente serviços públicos.** Consome `tools`, `systemPrompt` e a costura de aprovação; sem alterações em engine / agent-loop / apiproxy / UI oficial.
|
|
148
|
+
- **Zero rede, zero credenciais.** Banco de dados local com modo de arquivo POSIX `0600`.
|
|
149
|
+
- **Falha ruidosa.** Banco corrompido, esquema mais novo ou configuração inválida falha ao carregar; orçamentos cheios e correspondências de substring ambíguas falham com erros estruturados.
|
|
150
|
+
- **Um processo, um armazém.** Várias sessões compartilham o armazém SQLite; dois processos que compartilham um `$DSH_HOME` escrevem o mesmo arquivo (último escritor vence sob o bloqueio do SQLite).
|
|
137
151
|
|
|
138
|
-
|
|
152
|
+
## Known limitations
|
|
139
153
|
|
|
140
|
-
|
|
154
|
+
- **Eventos de sessão declarados, ainda não emitidos (rc.6).** `memory/added|updated|removed|recalled|snapshot` são declarados por fusão, mas o rc.6 não tem superfície de registro para tipos de evento fora do repo; a emissão é ativada quando uma build do harness os registrar.
|
|
155
|
+
- **A política `ask` precisa de um answerer.** Sem um answerer UI/ACP composto, as escritas falham fechadas.
|
|
156
|
+
- **Sem indexação FTS5.** A busca por substring usa `instr` insensível a maiúsculas (correto para CJK).
|
|
141
157
|
|
|
142
|
-
|
|
158
|
+
## What we learned from the terminal memories
|
|
143
159
|
|
|
144
|
-
-
|
|
145
|
-
- **Registro de adaptadores** — `ctx.memoryAdapters` permite que plugins de memória de terceiros falem o protocolo registrando um conversor de dados puro (`register()` reversível; a importação passa pelo `seed` com portão de aprovação, a exportação é somente leitura). Guia: [docs/adapters-guide.md](docs/adapters-guide.md) (chinês: [adapters-guide.zh.md](docs/adapters-guide.zh.md)).
|
|
160
|
+
O `dsh-memento` não é um port do Claude Code, Codex ou Hermes — mas seu design absorveu deliberadamente as partes que cada um acertou, e recusou as que causavam dano:
|
|
146
161
|
|
|
147
|
-
|
|
|
148
|
-
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
162
|
+
| Terminal memory | O que acertou | O que o dsh-memento adotou |
|
|
163
|
+
|---|---|---|
|
|
164
|
+
| **Claude Code** — `CLAUDE.md` | arquivos de memória em texto puro hierárquicos (nível usuário → nível projeto), legíveis e editáveis por humanos, mesclados automaticamente em toda sessão | entradas em texto puro; camadas `user-global` / `workspace` mescladas por sessão; um armazém que você pode navegar, `export` e auditar — transparência como característica |
|
|
165
|
+
| **Codex** — `AGENTS.md` | instruções com escopo por diretório auto-descobertas e injetadas com atrito zero para o modelo | a camada `workspace` indexada pelo cwd da sessão (insensível a maiúsculas no Windows); o snapshot congelado injetado automaticamente no início da sessão |
|
|
166
|
+
| **Hermes** — `memory.md` | gravações de memória proativas e a lição de segurança de que uma porta aplicada só na camada de ferramentas é contornável por injeção tardia de ferramenta | a ferramenta `memory` com orientação Save/Skip + propostas de auto-captura com porta de aprovação; a porta vive dentro dos métodos de escrita de `ctx.memory`, não na camada de ferramentas |
|
|
152
167
|
|
|
153
|
-
|
|
154
|
-
- **Proposta de upstream** — [docs/upstream-proposal.md](docs/upstream-proposal.md) (chinês: [upstream-proposal.zh.md](docs/upstream-proposal.zh.md)): por que a emenda oficial `ctx.memory` deveria adotar o protocolo, as diferenças e o caminho de migração.
|
|
168
|
+
Fontes: [Claude Code memory](https://code.claude.com/docs/en/memory) · [Codex AGENTS.md](https://developers.openai.com/codex/cli/agents-md) · [Hermes memory](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/memory.md) · [Hermes #48181](https://github.com/NousResearch/hermes-agent/issues/48181).
|
|
155
169
|
|
|
156
|
-
|
|
170
|
+
E as partes deliberadamente recusadas: a auto-resumização oculta em estado privado do modelo (os resumos de compactação aqui viram **propostas pendentes** que aguardam um approve/dismiss humano), as ambições de armazém/vector-store, e qualquer escrita sem aprovação ou trilha de auditoria visível para humanos. Também adotado: a ressalva documentada do Hermes de que dois processos que compartilham um diretório home escrevem o mesmo arquivo de memória — veja Security boundaries.
|
|
157
171
|
|
|
158
|
-
|
|
159
|
-
- **Zero rede, zero credenciais.** Banco de dados local; modo de arquivo POSIX `0600`.
|
|
160
|
-
- **Falhar ruidosamente.** Banco de dados corrompido ou schema mais novo falha no carregamento; orçamentos cheios e correspondências de substring ambíguas falham com erros estruturados. Nada é silenciosamente engolido ou truncado.
|
|
161
|
-
- **Um processo, um armazenamento.** Múltiplas sessões em um processo compartilham o armazenamento SQLite (escritas serializadas, auditoria por sessão). Dois **processos** compartilhando um `$DSH_HOME` gravam o mesmo arquivo: vence o último gravador sob o locking do SQLite — não execute duas instâncias do harness em um `$DSH_HOME` se você precisa de consistência entre processos (a mesma ressalva que o projeto Hermes documenta).
|
|
172
|
+
## Development
|
|
162
173
|
|
|
163
|
-
|
|
174
|
+
```sh
|
|
175
|
+
npm install # node ^22.19 || >=24
|
|
176
|
+
npm test # node --test: 133 tests
|
|
177
|
+
npm run test:conformance # dsh-memory-protocol v1 conformance suite
|
|
178
|
+
npm run typecheck # tsc --checkJs gate
|
|
179
|
+
npm run check:coverage # line-coverage gate
|
|
180
|
+
npm run check:readmes # five-language README consistency gate
|
|
181
|
+
```
|
|
164
182
|
|
|
165
|
-
|
|
166
|
-
- **A política `ask` precisa de um answerer.** Sem um answerer de UI/ACP composto, as escritas falham fechado (`unavailable`) — por design, a postura fail-closed da emenda de aprovação.
|
|
167
|
-
- **Sem índice FTS5.** A busca por substring usa `instr` insensível a maiúsculas (correto para CJK); o ranking de recuperação usa contadores de acertos por entrada. O tokenizador trigram do FTS5 não indexa caracteres CJK de um único caractere, então não é usado — veja [ARCHITECTURE.md](ARCHITECTURE.md), decisão 10.
|
|
183
|
+
`lib/` tem zero dependências de DSH (somente builtins de node:); importações de DSH existem apenas em `index.mjs`.
|
|
168
184
|
|
|
169
|
-
##
|
|
185
|
+
## Topics
|
|
170
186
|
|
|
171
|
-
|
|
172
|
-
npm install
|
|
173
|
-
npm test # node --test: 133 testes — orçamento, substring única, política do portão, armazenamento, snapshot, integração com mock-ctx (invariantes S2/S3), comando/recuperação/painel/importação V2, adaptadores de protocolo + conformidade
|
|
174
|
-
npm run test:conformance # suíte de conformidade dsh-memory-protocol v1 (referência dourada; terceiros usam --provider)
|
|
175
|
-
npm run typecheck # portão tsc --checkJs sobre index.mjs / lib / scripts
|
|
176
|
-
npm run check:coverage # portão de cobertura de linhas: lib ≥90%, index.mjs ≥85%, todos ≥90%
|
|
177
|
-
npm run check:readmes # portão de coerência dos cinco README
|
|
178
|
-
```
|
|
187
|
+
`dsh`, `dsh-plugin`, `deepseek-harness`, `memory`, `agent-memory`, `approval`, `audit`, `sqlite`, `cordis`, `llm`
|
|
179
188
|
|
|
180
|
-
|
|
189
|
+
## Contributors
|
|
181
190
|
|
|
182
|
-
|
|
191
|
+
- [@Niuniu-Sir](https://github.com/Niuniu-Sir) — o relato de falha de inicialização na [issue #1](https://github.com/PerryLink/dsh-memento/issues/1) que levou ao fallback `~/.dsh` incluído na 0.3.1.
|
|
183
192
|
|
|
184
|
-
|
|
193
|
+
## PerryLink DSH Plugin Family
|
|
185
194
|
|
|
186
|
-
|
|
195
|
+
Este projeto é um dos [15 plugins do DeepSeek Harness](https://github.com/PerryLink) mantidos por [PerryLink](https://github.com/PerryLink). Se este te ajuda, os demais provavelmente também:
|
|
187
196
|
|
|
188
|
-
|
|
197
|
+
| Plugin | One-liner |
|
|
198
|
+
|---|---|
|
|
199
|
+
| [dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel) | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors |
|
|
200
|
+
| [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | Engineering-discipline guard: requirements grill, test gates, adversary review |
|
|
201
|
+
| [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | Durable background child agents with a Web UI sidebar, messaging and interrupt |
|
|
202
|
+
| [dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions) | LSP diagnostics, formatting, completion, code actions and rename over language servers |
|
|
203
|
+
| [dsh-output-styles](https://github.com/PerryLink/dsh-output-styles) | Claude Code outputStyles-equivalent runtime style switching |
|
|
204
|
+
| [dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind) | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore |
|
|
205
|
+
| [dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules) | Claude Code-style declarative allow/deny/ask permission rules with audit |
|
|
206
|
+
| [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | Second-model auto-review on the approval chain, fail-closed by default |
|
|
207
|
+
| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool |
|
|
208
|
+
| [dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security) | Security-audit skill pack: secret scan, dependency and supply-chain review |
|
|
209
|
+
| [dsh-session-pin](https://github.com/PerryLink/dsh-session-pin) | Pin sessions in the Web sidebar with durable ordering |
|
|
210
|
+
| [dsh-composer-history](https://github.com/PerryLink/dsh-composer-history) | Terminal-style input history for the web composer: arrows, Ctrl+R search |
|
|
211
|
+
| [dsh-github](https://github.com/PerryLink/dsh-github) | GitHub PR/issues integration for DSH, every write gated by approval |
|
|
212
|
+
| [dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide) | Plugin-development knowledge base as an on-demand agent skill |
|
|
213
|
+
| [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH |
|
|
189
214
|
|
|
190
|
-
##
|
|
215
|
+
## License
|
|
191
216
|
|
|
192
|
-
Apache License 2.0
|
|
217
|
+
[Apache License 2.0](LICENSE) © 2026 dsh-memento contributors
|