dsh-memento 0.2.0 → 0.3.0
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 +140 -132
- package/CHANGELOG.md +67 -46
- package/README.es.md +167 -166
- package/README.hi.md +167 -166
- package/README.md +167 -166
- package/README.pt.md +167 -166
- package/README.zh.md +167 -166
- package/client/client.js +241 -240
- package/index.mjs +169 -35
- package/lib/constants.mjs +64 -58
- package/lib/store.mjs +675 -654
- package/package.json +93 -93
- package/types.d.ts +193 -191
package/README.pt.md
CHANGED
|
@@ -1,166 +1,167 @@
|
|
|
1
|
-
# dsh-memento
|
|
2
|
-
|
|
3
|
-
**Memória entre sessões limitada, em camadas, protegida por aprovação e auditável para o DeepSeek Harness.**
|
|
4
|
-
|
|
5
|
-
[](LICENSE)
|
|
6
|
-
[](https://www.npmjs.com/package/@deepseek-ai/dsh)
|
|
7
|
-
[](https://nodejs.org/)
|
|
8
|
-
[]()
|
|
9
|
-
[]()
|
|
10
|
-
|
|
11
|
-
[English](README.md) · [中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
|
|
12
|
-
|
|
13
|
-
> Outros plugins de memória vendem um **armazém**. O dsh-memento vende a **emenda (seam)**: um serviço tipado `ctx.memory`, um portão de aprovação de escrita que nenhum caminho de modelo pode contornar e trilhas de auditoria que você pode reconstruir a partir do log da sessão. Memória nativa em primeiro lugar para o DeepSeek Harness — protocolo + portão de confiança + auditoria, com zero rede e zero credenciais.
|
|
14
|
-
|
|
15
|
-
## ✨ Por que dsh-memento?
|
|
16
|
-
|
|
17
|
-
- **É uma emenda de capacidade, não mais um armazenamento.** Service Definition (`ctx.memory`), Provider local em SQLite (`node:sqlite`, WAL, `0600`) e Consumers (ferramenta `memory` + injeção de snapshot congelado). Qualquer plugin futuro — uma integração de semente `dsh-claude-move`, uma ponte, um painel — alimenta e lê o **mesmo armazenamento através do mesmo portão**.
|
|
18
|
-
- **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.
|
|
19
|
-
- **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.
|
|
20
|
-
- **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.
|
|
21
|
-
|
|
22
|
-
## ⚡ Início rápido
|
|
23
|
-
|
|
24
|
-
```sh
|
|
25
|
-
# requer Node ^22.19 || >=24 e DSH 0.1.0-rc.6
|
|
26
|
-
dsh plugin --profile web add dsh-memento # ou ./dsh-memento / um tarball / uma URL do GitHub
|
|
27
|
-
dsh --profile web --dump-config # espere uma camada "# == dsh-memento", sem FAILED na inicialização
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
Depois, na Web UI: peça ao modelo para lembrar algo → aprove a escrita → inicie uma **nova sessão** e pergunte o que ele lembra. Essa é a demonstração inteira.
|
|
31
|
-
|
|
32
|
-
```yaml
|
|
33
|
-
# substituição opcional no cordis.patch.yml do perfil
|
|
34
|
-
- id: memento
|
|
35
|
-
config:
|
|
36
|
-
writePolicy: ask # ask (padrão) | auto | off — invisível ao modelo
|
|
37
|
-
budgets:
|
|
38
|
-
user: { userGlobal: 4000, workspace: 2000 } # memória com muito chinês: aumente + anote o porquê
|
|
39
|
-
agent: { userGlobal: 4000, workspace: 4000 }
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
## 🧠 O que ele faz
|
|
43
|
-
|
|
44
|
-
| | Componente | O que você recebe |
|
|
45
|
-
| --- | --- | --- |
|
|
46
|
-
| 🧩 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 |
|
|
47
|
-
| 💾 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 |
|
|
48
|
-
| 🛠 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 |
|
|
49
|
-
|
|
50
|
-
**Duas trilhas × duas camadas × chave por agente.** Trilha `user` = fatos sobre o usuário (preferências, estilo de comunicação, pontos sensíveis); trilha `agent` = fatos do ambiente, convenções do projeto, lições aprendidas. Cada trilha tem camadas `user-global` (entre workspaces) e `workspace` (cwd por sessão) — camadas mescladas no estilo Codex, não global-apenas no estilo Hermes. Uma terceira dimensão isola entradas pelo `agentPreset` da sessão (escopo por agente); entradas sem preset ficam na camada compartilhada visível para todos.
|
|
51
|
-
|
|
52
|
-
**Snapshots congelados.** O snapshot é renderizado uma vez por sessão na primeira montagem do prompt (leitura síncrona do SQLite + cache por sessão) e nunca muda no meio da sessão — estável por cache de prefixo por construção. Mudanças internas da sessão persistem apenas em disco + auditoria.
|
|
53
|
-
|
|
54
|
-
```
|
|
55
|
-
Consumer: memory tool Consumer: frozen snapshot (systemPrompt section, order -50)
|
|
56
|
-
add/replace/remove/query per-session freeze, budget-headed
|
|
57
|
-
│ writes (agent+callId) │ reads (sync, session cwd)
|
|
58
|
-
▼ ▼
|
|
59
|
-
Service Definition: ctx.memory — budgets/add/replace/remove/query/seed
|
|
60
|
-
every write: budget precheck → ctx.approval.request (approval waterfall) → budget recheck → persist → audit
|
|
61
|
-
│
|
|
62
|
-
▼
|
|
63
|
-
Provider: lib/store.mjs — node:sqlite (WAL, 0600), entries + audit tables, unique-substring match
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
## 🧰 Instalar e desinstalar
|
|
67
|
-
|
|
68
|
-
```sh
|
|
69
|
-
dsh plugin --profile <name> add ./dsh-memento # checkout local (sem etapa de build)
|
|
70
|
-
dsh plugin --profile <name> add
|
|
71
|
-
dsh plugin --profile <name>
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `budgets.
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
- **`
|
|
103
|
-
-
|
|
104
|
-
-
|
|
105
|
-
- **
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
| **
|
|
115
|
-
| **
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
|
125
|
-
|
|
|
126
|
-
| dsh-
|
|
127
|
-
| dsh-
|
|
128
|
-
| dsh-
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
- **
|
|
139
|
-
- **
|
|
140
|
-
- **
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
- **
|
|
146
|
-
- **
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
npm
|
|
153
|
-
npm
|
|
154
|
-
npm run
|
|
155
|
-
npm run check:
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
1
|
+
# dsh-memento
|
|
2
|
+
|
|
3
|
+
**Memória entre sessões limitada, em camadas, protegida por aprovação e auditável para o DeepSeek Harness.**
|
|
4
|
+
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](https://www.npmjs.com/package/@deepseek-ai/dsh)
|
|
7
|
+
[](https://nodejs.org/)
|
|
8
|
+
[]()
|
|
9
|
+
[]()
|
|
10
|
+
|
|
11
|
+
[English](README.md) · [中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
|
|
12
|
+
|
|
13
|
+
> Outros plugins de memória vendem um **armazém**. O dsh-memento vende a **emenda (seam)**: um serviço tipado `ctx.memory`, um portão de aprovação de escrita que nenhum caminho de modelo pode contornar e trilhas de auditoria que você pode reconstruir a partir do log da sessão. Memória nativa em primeiro lugar para o DeepSeek Harness — protocolo + portão de confiança + auditoria, com zero rede e zero credenciais.
|
|
14
|
+
|
|
15
|
+
## ✨ Por que dsh-memento?
|
|
16
|
+
|
|
17
|
+
- **É uma emenda de capacidade, não mais um armazenamento.** Service Definition (`ctx.memory`), Provider local em SQLite (`node:sqlite`, WAL, `0600`) e Consumers (ferramenta `memory` + injeção de snapshot congelado). Qualquer plugin futuro — uma integração de semente `dsh-claude-move`, uma ponte, um painel — alimenta e lê o **mesmo armazenamento através do mesmo portão**.
|
|
18
|
+
- **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`.
|
|
19
|
+
- **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.
|
|
20
|
+
- **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.
|
|
21
|
+
|
|
22
|
+
## ⚡ Início rápido
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
# requer Node ^22.19 || >=24 e DSH 0.1.0-rc.6
|
|
26
|
+
dsh plugin --profile web add dsh-memento # ou ./dsh-memento / um tarball / uma URL do GitHub
|
|
27
|
+
dsh --profile web --dump-config # espere uma camada "# == dsh-memento", sem FAILED na inicialização
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Depois, na Web UI: peça ao modelo para lembrar algo → aprove a escrita → inicie uma **nova sessão** e pergunte o que ele lembra. Essa é a demonstração inteira.
|
|
31
|
+
|
|
32
|
+
```yaml
|
|
33
|
+
# substituição opcional no cordis.patch.yml do perfil
|
|
34
|
+
- id: memento
|
|
35
|
+
config:
|
|
36
|
+
writePolicy: ask # ask (padrão) | auto | off — invisível ao modelo
|
|
37
|
+
budgets:
|
|
38
|
+
user: { userGlobal: 4000, workspace: 2000 } # memória com muito chinês: aumente + anote o porquê
|
|
39
|
+
agent: { userGlobal: 4000, workspace: 4000 }
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## 🧠 O que ele faz
|
|
43
|
+
|
|
44
|
+
| | Componente | O que você recebe |
|
|
45
|
+
| --- | --- | --- |
|
|
46
|
+
| 🧩 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 |
|
|
47
|
+
| 💾 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 |
|
|
48
|
+
| 🛠 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 |
|
|
49
|
+
|
|
50
|
+
**Duas trilhas × duas camadas × chave por agente.** Trilha `user` = fatos sobre o usuário (preferências, estilo de comunicação, pontos sensíveis); trilha `agent` = fatos do ambiente, convenções do projeto, lições aprendidas. Cada trilha tem camadas `user-global` (entre workspaces) e `workspace` (cwd por sessão) — camadas mescladas no estilo Codex, não global-apenas no estilo Hermes. Uma terceira dimensão isola entradas pelo `agentPreset` da sessão (escopo por agente); entradas sem preset ficam na camada compartilhada visível para todos. Leituras e localização de escrita com escopo de sessão seguem a mesma visibilidade: uma sessão vê — e `replace`/`remove` só podem tocar — entradas compartilhadas mais as do próprio agente, e entradas `workspace` apenas do próprio cwd. As superfícies de gestão (`/memory`, o painel) mantêm a visão completa entre agentes.
|
|
51
|
+
|
|
52
|
+
**Snapshots congelados.** O snapshot é renderizado uma vez por sessão na primeira montagem do prompt (leitura síncrona do SQLite + cache por sessão) e nunca muda no meio da sessão — estável por cache de prefixo por construção. Mudanças internas da sessão persistem apenas em disco + auditoria.
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
Consumer: memory tool Consumer: frozen snapshot (systemPrompt section, order -50)
|
|
56
|
+
add/replace/remove/query per-session freeze, budget-headed
|
|
57
|
+
│ writes (agent+callId) │ reads (sync, session cwd)
|
|
58
|
+
▼ ▼
|
|
59
|
+
Service Definition: ctx.memory — budgets/add/replace/remove/query/seed
|
|
60
|
+
every write: budget precheck → ctx.approval.request (approval waterfall) → budget recheck → persist → audit
|
|
61
|
+
│
|
|
62
|
+
▼
|
|
63
|
+
Provider: lib/store.mjs — node:sqlite (WAL, 0600), entries + audit tables, unique-substring match
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## 🧰 Instalar e desinstalar
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
dsh plugin --profile <name> add ./dsh-memento # checkout local (sem etapa de build)
|
|
70
|
+
dsh plugin --profile <name> add dsh-memento # pacote npm (publicado desde 0.2.0)
|
|
71
|
+
dsh plugin --profile <name> add git+https://github.com/PerryLink/dsh-memento.git # instalação pelo GitHub
|
|
72
|
+
dsh plugin --profile <name> remove dsh-memento # desinstalar: o BD + os logs de sessão são mantidos
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Após desinstalar, o banco de dados de memória e os logs de sessão que registraram a atividade de memória permanecem; sessões antigas continuam carregáveis.
|
|
76
|
+
|
|
77
|
+
## ⚙️ Configuração
|
|
78
|
+
|
|
79
|
+
Todo campo é um `Config` Schemastery validado; valores inválidos falham ruidosamente no carregamento. Substitua no cordis.yml sob a linha `memento`.
|
|
80
|
+
|
|
81
|
+
| Campo | Padrão | Significado |
|
|
82
|
+
| --- | --- | --- |
|
|
83
|
+
| `enabled` | `true` | `false` remove o serviço, as ferramentas, o snapshot, o comando, o painel e o answerer por completo (sem estado parcial) |
|
|
84
|
+
| `dbPath` | `''` → `$DSH_HOME/dsh-memento/memory.db` | absoluto, ou relativo a `$DSH_HOME` |
|
|
85
|
+
| `budgets.user.userGlobal` / `budgets.user.workspace` | `2000` / `2000` | orçamento rígido de caracteres por camada da trilha user |
|
|
86
|
+
| `budgets.agent.userGlobal` / `budgets.agent.workspace` | `4000` / `4000` | orçamento rígido de caracteres por camada da trilha agent |
|
|
87
|
+
| `writePolicy` | `'ask'` | `'ask'` = aprovação do usuário; `'auto'` = permite passar (fonte da aprovação registrada); `'off'` = rejeita. Invisível ao modelo |
|
|
88
|
+
| `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` |
|
|
89
|
+
| `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 |
|
|
90
|
+
| `snapshotOrder` | `-50` | ordem da seção do snapshot: depois da identidade do harness (`-100`), antes da persona (`0`) |
|
|
91
|
+
| `maxEntriesPerQuery` | `20` | limite padrão de resultados por consulta (`limit` explícito permitido, teto rígido 1000) |
|
|
92
|
+
| `commandListLimit` | `50` | entradas exibidas por comando `/memory list` / `query` |
|
|
93
|
+
| `commandAuditLimit` | `10` | linhas de auditoria exibidas por comando `/memory audit` |
|
|
94
|
+
| `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 |
|
|
95
|
+
| `panelEntriesLimit` | `200` | tamanho da página de entradas do painel web (e teto) |
|
|
96
|
+
| `panelAuditLimit` | `20` | linhas de auditoria do painel web por padrão (teto 200) |
|
|
97
|
+
| `auditRetentionDays` | `0` | retenção de auditoria: 0 = para sempre, >0 = poda ao abrir a loja |
|
|
98
|
+
| `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 |
|
|
99
|
+
|
|
100
|
+
## 🛠 Ferramentas e superfícies
|
|
101
|
+
|
|
102
|
+
- **`memory`** — add/replace/remove/consolidate/query com orientação de Salvar/Pular embutida na descrição (salve preferências do usuário, correções, fatos do ambiente, convenções, lições; pule trivialidades, fatos rederiváveis, despejos, caminhos de uso único). Escritas passam pelo portão de aprovação; leituras são livres; replace/remove miram uma **substring única** (correspondências ambíguas falham com a lista de candidatos); consolidate mescla 1..20 entradas em uma com uma única aprovação e uma escrita atômica.
|
|
103
|
+
- **`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).
|
|
104
|
+
- **`/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` · `import <path>`. 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. Entradas importadas ganham ids e carimbos de tempo novos; propostas, linhas de auditoria e contadores de recuperação não são migrados.
|
|
105
|
+
- **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.
|
|
106
|
+
- **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.
|
|
107
|
+
|
|
108
|
+
## 🎓 O que aprendemos com as memórias de terminal
|
|
109
|
+
|
|
110
|
+
dsh-memento não é um port do Claude Code, do Codex ou do Hermes — mas seu design absorveu deliberadamente as partes que cada um acertou e recusou as partes que machucam:
|
|
111
|
+
|
|
112
|
+
| Memória de terminal | O que acertou | O que o dsh-memento adotou |
|
|
113
|
+
| --- | --- | --- |
|
|
114
|
+
| **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 |
|
|
115
|
+
| **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 |
|
|
116
|
+
| **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 |
|
|
117
|
+
|
|
118
|
+
Fontes: [memória do Claude Code](https://code.claude.com/docs/en/memory) · [AGENTS.md do Codex](https://developers.openai.com/codex/cli/agents-md) · [memória do Hermes](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).
|
|
119
|
+
|
|
120
|
+
E as partes que recusamos deliberadamente: auto-resumir de forma oculta para estado privado do modelo (aqui os resumos de compactação viram **propostas pendentes** que aguardam um aprovar/descartar humano), ambições de armazém/vetorial, e qualquer escrita sem aprovação ou trilha de auditoria visível ao humano. Também adotamos a ressalva documentada do Hermes: dois processos compartilhando um diretório home escrevem o mesmo arquivo de memória — veja Limites de segurança.
|
|
121
|
+
|
|
122
|
+
## 🆚 Como ele é diferente
|
|
123
|
+
|
|
124
|
+
| Plugin | O que é | A diferença do dsh-memento |
|
|
125
|
+
| --- | --- | --- |
|
|
126
|
+
| dsh-memory-evolve | armazém de memória / loops de evolução | uma emenda de serviço tipada, portão de aprovação e auditoria de log de sessão; sem ambição de armazém |
|
|
127
|
+
| dsh-mnemon | helper de armazenamento de memória | protocolo + portão + auditoria, não mais um armazenamento |
|
|
128
|
+
| 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` |
|
|
129
|
+
| 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 |
|
|
130
|
+
| claude-bridge | ponte para o Claude Code | nativo de DSH; um futuro caminho `seed(source:'claude')` permite que uma ponte alimente o mesmo armazenamento |
|
|
131
|
+
| dsh-external/Recall | memória de agente externo | local em primeiro lugar, zero rede, usa a própria emenda de aprovação do DSH |
|
|
132
|
+
| 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 |
|
|
133
|
+
|
|
134
|
+
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`.
|
|
135
|
+
|
|
136
|
+
## 🔒 Limites de segurança
|
|
137
|
+
|
|
138
|
+
- **Somente serviços públicos** (`tools`, `systemPrompt`, a emenda de aprovação). Sem mudanças em engine / agent-loop / apiproxy / UI oficial.
|
|
139
|
+
- **Zero rede, zero credenciais.** Banco de dados local; modo de arquivo POSIX `0600`.
|
|
140
|
+
- **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.
|
|
141
|
+
- **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).
|
|
142
|
+
|
|
143
|
+
## ⚠️ Limitações conhecidas
|
|
144
|
+
|
|
145
|
+
- **O vocabulário de eventos de sessão é declarado, ainda não emitido (rc.6).** `memory/added|updated|removed|recalled|snapshot` são declarados por merge em `types.d.ts`, mas o rc.6 não tem superfície de registro para tipos de evento fora do repositório (appends não registrados tornariam sessões persistidas incapazes de carregar). A completude da auditoria vem do par de aprovação + a tabela de auditoria; a emissão liga automaticamente assim que um build do harness registra os tipos. Veja [ARCHITECTURE.md](ARCHITECTURE.md) decisão 4.
|
|
146
|
+
- **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.
|
|
147
|
+
- **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.
|
|
148
|
+
|
|
149
|
+
## 🧪 Desenvolvimento
|
|
150
|
+
|
|
151
|
+
```sh
|
|
152
|
+
npm install
|
|
153
|
+
npm test # node --test: 112 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
|
|
154
|
+
npm run typecheck # portão tsc --checkJs sobre index.mjs / lib / scripts
|
|
155
|
+
npm run check:coverage # portão de cobertura de linhas: lib ≥90%, index.mjs ≥85%, todos ≥90%
|
|
156
|
+
npm run check:readmes # portão de coerência dos cinco README
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
`lib/` tem zero dependência de DSH (somente builtins do node:); imports de DSH existem apenas em `index.mjs`. Disciplina completa em [AGENTS.md](AGENTS.md); decisões de design em [ARCHITECTURE.md](ARCHITECTURE.md).
|
|
160
|
+
|
|
161
|
+
## 🏷 Tópicos
|
|
162
|
+
|
|
163
|
+
Tópicos sugeridos para o GitHub: `dsh` · `dsh-plugin` · `deepseek-harness` · `memory` · `agent-memory` · `approval` · `audit` · `sqlite` · `cordis` · `llm`
|
|
164
|
+
|
|
165
|
+
## 📄 Licença
|
|
166
|
+
|
|
167
|
+
Apache License 2.0 — veja [LICENSE](LICENSE). Nenhum código de terceiros é redistribuído; veja [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|