stratagate-dsh 0.3.42 → 0.3.43
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/README.md +188 -145
- package/README.zh-CN.md +185 -144
- package/dist/client.js +1 -1
- package/dist/plugin.js +190 -56
- package/dist/plugin.js.map +1 -1
- package/docs/assets/stratagate-conversation-memory-en.png +0 -0
- package/docs/assets/stratagate-conversation-memory-zh.png +0 -0
- package/docs/assets/stratagate-long-term-memory-views-en-v2.png +0 -0
- package/docs/assets/stratagate-long-term-memory-views-zh-v2.png +0 -0
- package/docs/assets/stratagate-memory-workflow-en-v2.png +0 -0
- package/docs/assets/stratagate-memory-workflow-zh-v2.png +0 -0
- package/docs/development-validation.md +36 -4
- package/package.json +1 -1
- package/packages/core/src/blocks.ts +24 -0
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ Project source, releases, and issues are available on [GitHub](https://github.co
|
|
|
8
8
|
|
|
9
9
|
### Recent conversations stay detailed. Older memories grow more concise.
|
|
10
10
|
|
|
11
|
-
StrataGate is a cross-session memory plugin for DeepSeek Harness.
|
|
11
|
+
StrataGate is a cross-session memory plugin for DeepSeek Harness. Daily notes help resume recent work, layered conversation memory preserves historical detail that can be expanded, and long-term Events and the topic directory retain important information and help locate its sources. The knowledge graph, semantic vector retrieval, and reranking can be enabled as needed.
|
|
12
12
|
|
|
13
13
|
<p align="center">
|
|
14
14
|
<a href="https://github.com/diqierjia/StrataGate-AgentMemory/actions/workflows/ci.yml"><img src="https://github.com/diqierjia/StrataGate-AgentMemory/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
|
|
@@ -55,33 +55,35 @@ StrataGate is a cross-session memory plugin for DeepSeek Harness. Recent convers
|
|
|
55
55
|
|
|
56
56
|
## Why StrataGate?
|
|
57
57
|
|
|
58
|
-
1. **
|
|
58
|
+
1. **Daily notes carry work forward; historical conversations can be expanded.**
|
|
59
59
|
|
|
60
|
-
(1) **
|
|
60
|
+
(1) **Daily notes help resume work.** The agent records progress, intermediate results, useful lessons from failures, blockers, and next steps by date. New sessions include notes from the three most recent dates with notes by default, reducing the need to repeat background information. → [Daily notes](#daily-notes)
|
|
61
61
|
|
|
62
|
-
(2) **
|
|
62
|
+
(2) **Conversation memory keeps recent detail and makes older history concise.** Each conversation block has six views, L0–L5, with different levels of detail. As more conversation accumulates, older dialogue gradually becomes key facts, short summaries, and title indexes, reducing the context occupied by history. → [Layered conversation memory](#layered-memory)
|
|
63
63
|
|
|
64
|
-
|
|
64
|
+
(3) **Views shrink while original records remain.** Complete L5 source messages and tool records are preserved. When details need checking, the agent can expand a memory to recover the original wording and context. → [Layered conversation memory](#layered-memory)
|
|
65
65
|
|
|
66
|
-
|
|
66
|
+

|
|
67
67
|
|
|
68
|
-
|
|
68
|
+
2. **Long-term memory retains important information and helps trace sources and changes.**
|
|
69
69
|
|
|
70
|
-
(
|
|
70
|
+
(1) **Events record what happened.** Important decisions, preferences, requirements, and changes become Events with scope, time, and source references. AI evaluates potential duplicates; uncertain cases can be reviewed by the user, and the processing history remains traceable. → [Event memory](#event-cards)
|
|
71
71
|
|
|
72
|
-
(
|
|
72
|
+
(2) **The topic directory shows what has been remembered.** Related Events form chapters, sections, and source-linked overviews. The agent can browse topics before retrieving specific Events. Users can also start Dreaming, a dedicated agent that reviews and organizes the existing directory. → [Topic directory](#memory-topics)
|
|
73
73
|
|
|
74
|
-
(
|
|
74
|
+
(3) **The optional knowledge graph organizes current state.** When enabled, it derives current information and relationships about people, projects, tools, and other entities from Events, retaining their sources. The graph is off by default; Event cards, topics, and ordinary retrieval work independently. → [Current-state graph](#current-state-graph)
|
|
75
75
|
|
|
76
|
-
(
|
|
76
|
+
(4) **Retrieval can be enhanced as needed.** Default retrieval uses keyword-based and related mechanisms. Configuring an embedding model adds semantically similar Events; a separately configured reranking model can refine the order of automatic recall results.
|
|
77
|
+
|
|
78
|
+
(5) **Bring memories from other AIs.** Imported content can become traceable long-term Events while the original imported text remains preserved. → [External memory import](#external-memory-import)
|
|
77
79
|
|
|
78
80
|
3. **Evidence gate: check whether retrieved evidence is sufficient before answering.**
|
|
79
81
|
|
|
80
|
-
|
|
82
|
+
Daily notes help resume work, while topic overviews help locate information. Historical facts still need checking against source Events or original records. A relevant search result may be insufficient to answer the question. The agent assesses the evidence and searches again or expands sources when needed. If it still cannot confirm the answer, it states the uncertainty. → [Evidence gate](#evidence-gate)
|
|
81
83
|
|
|
82
84
|
4. **Retrieval hits do not automatically reinforce memory.**
|
|
83
85
|
|
|
84
|
-
Search hits, automatic context injection, and topic browsing do not trigger reinforcement. In the retrieval-use workflow, Events recorded as actually used in the final answer increase the adoption count and reset the decay anchor. More adoptions mean slower future decay. Explicit memory recording can also reinforce an existing record when the information is confirmed as a
|
|
86
|
+
Search hits, automatic context injection, and topic browsing do not trigger reinforcement. In the retrieval-use workflow, only Events recorded as actually used in the final answer increase the adoption count and reset the decay anchor. More adoptions mean slower future decay. Explicit memory recording can also reinforce an existing record when the information is confirmed as an exact duplicate of a currently valid fact. → [Weights and adoption-based reinforcement](#use-only-reinforcement)
|
|
85
87
|
|
|
86
88
|
Get started: → [Quick start](#quick-start-deepseek-harness)
|
|
87
89
|
|
|
@@ -89,78 +91,97 @@ Get started: → [Quick start](#quick-start-deepseek-harness)
|
|
|
89
91
|
|
|
90
92
|
## Quick start: DeepSeek Harness
|
|
91
93
|
|
|
92
|
-
|
|
94
|
+
Already using DeepSeek Harness? Copy this prompt to your agent:
|
|
93
95
|
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
+
```text
|
|
97
|
+
Follow https://github.com/diqierjia/StrataGate-AgentMemory/blob/main/docs/DSH.md to install StrataGate in my current DeepSeek Harness profile. Check version compatibility and verify that the plugin loads successfully. Let me know if a restart is required or you cannot identify the profile.
|
|
96
98
|
```
|
|
97
99
|
|
|
98
|
-
|
|
100
|
+
Or install manually (replace `web` with your profile name):
|
|
99
101
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
By default, the database is stored at:
|
|
103
|
-
|
|
104
|
-
```text
|
|
105
|
-
DSH_HOME/stratagate/memory.db
|
|
102
|
+
```bash
|
|
103
|
+
dsh plugin --profile web add stratagate-dsh
|
|
106
104
|
```
|
|
107
105
|
|
|
108
|
-
|
|
106
|
+
Restart the profile to begin automatically capturing conversations and organizing memories. View them under **DSH Settings → StrataGate-AgentMemory**.
|
|
109
107
|
|
|
110
|
-
|
|
108
|
+
See the [plugin guide](docs/DSH.md) for configuration, supported versions, and troubleshooting.
|
|
111
109
|
|
|
112
110
|
<a id="how-stratagate-works"></a>
|
|
113
111
|
|
|
114
112
|
## How it works
|
|
115
113
|
|
|
116
|
-

|
|
117
115
|
|
|
118
|
-
|
|
119
|
-
2. **Organize lasting information.** Facts, decisions, preferences, and requirements with future value become Events with time, scope, and source references. The graph organizes current state, while the topic directory and overviews organize related Events into chapters and sections.
|
|
120
|
-
3. **Recall when answering.** The plugin supplies the active conversation, any configured persistent Profile, a small set of relevant memories, and a concise topic directory. When more information is needed, the agent can search Events, the graph, or original records directly, or browse topics and open an overview before retrieving source Events.
|
|
121
|
-
4. **Assess evidence and record actual use.** The agent checks whether explicitly retrieved evidence is sufficient. It searches or expands further when needed, answers using sufficient evidence, and records the Events actually adopted to update their long-term weights.
|
|
116
|
+
StrataGate preserves conversation sources while organizing recent work and lasting information. When answering, the agent uses the available context first and retrieves more detail when needed.
|
|
122
117
|
|
|
123
|
-
|
|
118
|
+
1. **Save conversations and preserve the originals.** Completed turns form memory Blocks, each stored as six views, L0–L5, with different levels of detail. Older Blocks display more concise views by default and can be expanded when needed; complete original records remain preserved.
|
|
119
|
+
2. **Maintain daily notes to resume recent work.** The agent records progress, intermediate results, useful lessons from failures, blockers, and next steps as needed, with one Markdown file per day in each memory space. New sessions include notes from the three most recent dates with notes by default, helping continue earlier work.
|
|
120
|
+
3. **Organize lasting information and provide ways to find it.** Facts, decisions, preferences, and requirements with future value become Events with time, scope, and source references. The topic directory organizes related Events into chapters, sections, and overviews. When the knowledge graph is enabled, it also derives current state and relationships from Events.
|
|
121
|
+
4. **Use available context and retrieve detail as needed.** The plugin supplies the current conversation, any configured persistent Profile, recent notes, a small set of relevant memories, and a concise topic directory. If that information is sufficient, the agent answers directly. Otherwise, it searches Events or original records, or browses topics and follows their sources. With the graph enabled, it can also search entities and relationships.
|
|
122
|
+
5. **Check evidence and record actual use.** The agent assesses whether explicitly retrieved evidence is sufficient, searches further if needed, and answers using sufficient evidence. It records the Events actually used to update memory weights. Searching, browsing the directory, or reading daily notes does not by itself trigger reinforcement.
|
|
124
123
|
|
|
125
|
-
|
|
124
|
+
Automatic recall includes at most **4 Events** and, when the graph is enabled, up to **4 graph nodes**, sharing a budget of approximately **900 tokens**. The topic directory has a separate budget of approximately **400 tokens**. Daily notes, the persistent Profile, layered conversation memory, and unsealed turns are supplied separately.
|
|
126
125
|
|
|
127
126
|
## Core design
|
|
128
127
|
|
|
129
|
-
|
|
128
|
+
Each type of memory serves a different purpose:
|
|
129
|
+
|
|
130
|
+
| Component | What it stores | Main purpose |
|
|
130
131
|
| --- | --- | --- |
|
|
131
|
-
|
|
|
132
|
-
|
|
|
132
|
+
| **Daily notes** | Recent progress, results, blockers, and next steps | Resume work in a new session |
|
|
133
|
+
| **Conversation memory: Block** | Six views of the same conversation, from index to original records | Reduce default history while keeping detail recoverable |
|
|
134
|
+
| **Event memory: Event** | Useful lasting information with time, scope, and sources | Find facts, decisions, and historical changes |
|
|
135
|
+
| **Topic directory: Topic** | Chapters, sections, and source-linked overviews of related Events | Find specific memories from a vague recollection |
|
|
136
|
+
| **Knowledge graph: Graph (optional)** | Current state and entity relationships derived from Events | Query current information and connections |
|
|
137
|
+
| **Persistent Profile** | User information relevant to every conversation | Supply configured preferences such as language and form of address |
|
|
138
|
+
|
|
139
|
+
The agent maintains daily notes, the graph and topics are derived from Events, and the Profile is stored separately. Conversation simplification and Event weight decay follow conversation progress rather than elapsed calendar days.
|
|
140
|
+
|
|
141
|
+
<a id="daily-notes"></a>
|
|
142
|
+
|
|
143
|
+
### 1. Short-term memory: resume work with daily notes
|
|
144
|
+
|
|
145
|
+
The agent writes daily notes as needed to record progress, intermediate results, useful lessons from failures, blockers, and next steps. Each memory space stores one Markdown file per day, helping new sessions understand where work stopped and what comes next.
|
|
146
|
+
|
|
147
|
+
For example, a project note might contain:
|
|
148
|
+
|
|
149
|
+
```text
|
|
150
|
+
Project X: dependency migration
|
|
151
|
+
|
|
152
|
+
Completed: switched the project to pnpm.
|
|
153
|
+
Pending: verify whether CI passes after migration.
|
|
154
|
+
Next: run CI and check build and test results.
|
|
155
|
+
```
|
|
133
156
|
|
|
134
|
-
|
|
157
|
+
**New sessions reference recent notes by default.** Notes from the three most recent dates with notes are included by default; this number can be set to 1–30. Older notes remain searchable by date or keyword. Each session fixes a note snapshot when first loaded. Later writes do not repeatedly change that context, and the latest content can be read again when needed.
|
|
135
158
|
|
|
136
|
-
|
|
159
|
+
**Notes help resume work; historical facts remain verifiable.** The agent maintains the notes, which are not complete conversation records. To verify a decision, date, or reason, retrieve Events and original messages. Reading notes does not reinforce memory.
|
|
137
160
|
|
|
138
|
-
|
|
161
|
+
View notes under **DSH Settings → StrataGate-AgentMemory → Short-term memory**. Disabling daily notes stops writes and automatic inclusion while preserving existing files.
|
|
139
162
|
|
|
140
163
|
<a id="layered-memory"></a>
|
|
141
164
|
|
|
142
|
-
###
|
|
165
|
+
### 2. Conversation memory: condense older dialogue and recover detail when needed
|
|
143
166
|
|
|
144
|
-
|
|
167
|
+
Daily notes summarize recent work, while conversation memory preserves the original discussion. StrataGate stores several levels of detail for the same conversation and gradually reduces the history included by default as more conversation accumulates.
|
|
145
168
|
|
|
146
|
-

|
|
147
170
|
|
|
148
171
|
**One conversation block, six levels of detail.**
|
|
149
172
|
|
|
150
|
-
The DeepSeek Harness plugin seals a Block every **6 complete turns** by default. A turn consists of a user question and the assistant's complete response. The Block size is configurable;
|
|
151
|
-
|
|
152
|
-
Each fully processed Block contains these views:
|
|
173
|
+
The DeepSeek Harness plugin seals a memory Block every **6 complete turns** by default. A turn consists of a user question and the assistant's complete response. The Block size is configurable; content below the boundary remains in the current conversation.
|
|
153
174
|
|
|
154
175
|
| Level | Contents | Primary use |
|
|
155
176
|
| --- | --- | --- |
|
|
156
|
-
| L0 | Title and tags | Identify a piece of history
|
|
157
|
-
| L1 | Short summary | Understand the discussion's topic |
|
|
158
|
-
| L2 | Key facts | Review decisions, constraints, plans, and outcomes |
|
|
159
|
-
| L3 |
|
|
160
|
-
| L4 |
|
|
161
|
-
| L5 | Source messages and tool records | Verify
|
|
177
|
+
| **L0** | Title and tags | Identify a piece of history |
|
|
178
|
+
| **L1** | Short summary | Understand the discussion's topic |
|
|
179
|
+
| **L2** | Key facts | Review decisions, constraints, plans, and outcomes |
|
|
180
|
+
| **L3** | Dialogue condensed by fixed rules | Remove standalone fillers and repeated long text; compact tool records |
|
|
181
|
+
| **L4** | Readable, near-verbatim dialogue | Preserve user and assistant wording; compact recognized tool records |
|
|
182
|
+
| **L5** | Source messages and tool records | Verify original wording, complete context, and tool results |
|
|
162
183
|
|
|
163
|
-
The model summarizes L0–L2
|
|
184
|
+
The model summarizes L0–L2; fixed rules generate L3/L4. L3 removes further redundancy, while L4 stays close to the original wording. **None of these views overwrites the L5 source records.**
|
|
164
185
|
|
|
165
186
|
<details>
|
|
166
187
|
<summary>Exact pruning rules, decay formula, and level thresholds</summary>
|
|
@@ -173,8 +194,6 @@ The model produces L0–L2 summaries. L3 and L4 do not use model paraphrasing; c
|
|
|
173
194
|
|
|
174
195
|
Source records are saved first, followed by summarization and Event processing. Only a fully processed, ready Block can replace its corresponding native history and participate in decay.
|
|
175
196
|
|
|
176
|
-
**As more conversation accumulates, older Blocks default to less detail.**
|
|
177
|
-
|
|
178
197
|
Display changes follow exponential decay:
|
|
179
198
|
|
|
180
199
|
<p align="center"><strong>w<sub>block</sub>(age) = e<sup>−λ<sub>block</sub> · age</sup></strong></p>
|
|
@@ -198,98 +217,123 @@ The figure illustrates the trend. Actual changes depend on both the decay coeffi
|
|
|
198
217
|
|
|
199
218
|
</details>
|
|
200
219
|
|
|
201
|
-
**
|
|
220
|
+
**As more conversation accumulates, older Blocks default to less detail.**
|
|
202
221
|
|
|
203
|
-
|
|
222
|
+
Conversation memory becomes concise according to the number of subsequent ready Blocks, not elapsed calendar days. The decay setting controls how long detailed views remain and can be adjusted in settings.
|
|
204
223
|
|
|
205
|
-
|
|
224
|
+
**The agent can expand sources, and users can choose a level manually.**
|
|
206
225
|
|
|
207
|
-
If the user asks why pnpm was chosen, the agent can
|
|
226
|
+
For example, an older conversation currently shows only “Discussed the project's technical approach.” If the user asks why pnpm was originally chosen, the agent can read more detailed dialogue or the original records to find the reason.
|
|
208
227
|
|
|
209
|
-
|
|
228
|
+
The layered-content preview is for viewing only. Choosing an action such as “Let the assistant reference L4” attempts to apply that content to the conversation. The interface distinguishes an applied choice, a pending choice, and one that cannot be applied.
|
|
210
229
|
|
|
211
|
-
|
|
230
|
+
A user's manually chosen level takes priority over automatic compression and the agent's evidence reads. If context capacity is insufficient, the system first tries to condense other automatically managed history while preserving other manual choices; if that is still insufficient, it explains why. A manual choice resets the decay anchor, and the view can gradually become concise again as subsequent conversation accumulates.
|
|
212
231
|
|
|
213
232
|
<a id="event-cards"></a>
|
|
214
233
|
|
|
215
|
-
###
|
|
234
|
+
### 3. Long-term memory: retain important information and trace its sources and changes
|
|
216
235
|
|
|
217
|
-
|
|
236
|
+
Long-term memory organizes information with future value into Events and provides a topic directory to help find it. The optional knowledge graph organizes current state and relationships. The persistent Profile is stored separately and supplies configured user information in each conversation.
|
|
218
237
|
|
|
219
|
-

|
|
220
239
|
|
|
221
|
-
|
|
240
|
+
The figure uses sample data. Its graph view illustrates the functionality when enabled.
|
|
222
241
|
|
|
223
|
-
|
|
242
|
+
#### 3.1 Event memory: retain information with future value
|
|
224
243
|
|
|
225
|
-
|
|
244
|
+
Important facts, decisions, preferences, requirements, and changes can be saved as Events. Each Event retains its content, scope, source messages, and any temporal information that can be established. A Block can produce multiple Events or contain nothing that needs extraction.
|
|
226
245
|
|
|
227
246
|
| Time | Meaning |
|
|
228
247
|
| --- | --- |
|
|
229
248
|
| Mention time | When the conversation referred to the event |
|
|
230
249
|
| Occurrence time | When the event happened or is planned to happen |
|
|
231
250
|
|
|
232
|
-
If a user says “Finish the prototype next week” on May 6, May 6 is the mention date, while “next week” describes the planned completion time.
|
|
251
|
+
If a user says “Finish the prototype next week” on May 6, May 6 is the mention date, while “next week” describes the planned completion time. This record cannot serve as evidence that the prototype is complete. Uncertain dates retain their original wording and uncertainty.
|
|
252
|
+
|
|
253
|
+
**Retain useful information rather than recording every execution step.** Explicit requirements, corrections, changed decisions, confirmed causes, platform limitations, failure conditions, and meaningful outcomes may be worth retaining. Routine file reads, tool calls, and repeated tests do not each become Events merely because they occurred.
|
|
233
254
|
|
|
234
|
-
|
|
255
|
+
Records also need an appropriate scope. For example, “Align the arrows in this image” belongs to the current task and must not automatically become a permanent aesthetic preference. The agent can also use the active-memory tool to save information worth recalling later, without waiting for a Block to seal.
|
|
235
256
|
|
|
236
|
-
|
|
257
|
+
See the [Event extraction guide (Chinese)](docs/event-extractor.md) for detailed rules.
|
|
237
258
|
|
|
238
|
-
|
|
259
|
+
#### 3.2 Memory updates: distinguish additions, changes, conflicts, and duplicates
|
|
239
260
|
|
|
240
|
-
|
|
261
|
+
New information can lead to different updates:
|
|
241
262
|
|
|
242
|
-
|
|
263
|
+
| New information | How to interpret it |
|
|
264
|
+
| --- | --- |
|
|
265
|
+
| “The project switched from npm to pnpm” | Update the current choice while retaining the earlier decision and its sources |
|
|
266
|
+
| “Post-migration CI verification is pending” | Add an open question, not a claim that tests have passed |
|
|
267
|
+
| Two statements conflict and their validity is unresolved | Retain the conflict for further verification |
|
|
268
|
+
| Several records may describe the same event | Check their complete contents and sources before deciding whether to merge |
|
|
243
269
|
|
|
244
|
-
|
|
270
|
+
**Similarity does not establish duplication, and later progress does not make earlier records useless.** After code discovers potential duplicates, AI evaluates both records and their sources. Clearly distinct facts can remain separate; uncertain or unfinished cases are presented for user review.
|
|
245
271
|
|
|
246
|
-
|
|
272
|
+
Users can inspect both sources, edit a merged draft, keep either record, or keep both. Processing history and an undo entry point help trace changes before and after organization.
|
|
247
273
|
|
|
248
274
|
<a id="current-state-graph"></a>
|
|
249
275
|
|
|
250
|
-
|
|
276
|
+
#### 3.3 Knowledge graph: explore current state and relationships when needed
|
|
277
|
+
|
|
278
|
+
The knowledge graph derives people, projects, organizations, tools, places, and relationships such as “uses,” “participates in,” and “depends on” from Events. Node attributes and relationships retain their sources, helping answer what is currently true and how entities connect.
|
|
251
279
|
|
|
252
|
-
|
|
280
|
+
In the example, “the project uses pnpm” represents the current choice, while “CI verification pending” represents an unconfirmed result. The state changes only when new source evidence confirms it.
|
|
253
281
|
|
|
254
|
-
|
|
255
|
-
- a question about when it changed can inspect the change Event;
|
|
256
|
-
- a question about why it changed can expand the Event and check the original discussion.
|
|
282
|
+
**The graph is off by default; other memory features remain available.** Enabling it adds model calls to organize entities and relationships. Use **More → Advanced settings → Memory configuration → Enable knowledge graph**. If historical Events need backfilling, the interface shows the amount of work for confirmation before starting.
|
|
257
283
|
|
|
258
|
-
|
|
284
|
+
Disabling the graph stops its processing, queries, and automatic recall while preserving existing graph data and sources. Event cards, topics, ordinary retrieval, and the persistent Profile work independently.
|
|
259
285
|
|
|
260
286
|
<a id="memory-topics"></a>
|
|
261
287
|
|
|
262
|
-
|
|
288
|
+
#### 3.4 Topic directory: find specific memories from a vague recollection
|
|
263
289
|
|
|
264
|
-
With clear keywords,
|
|
290
|
+
With clear keywords, search directly. With only a vague recollection of an earlier discussion, browse the topic directory first.
|
|
265
291
|
|
|
266
|
-
|
|
292
|
+
A Topic represents a lasting subject such as “Project X,” with sections for related matters such as “Dependencies and build.” On-demand overviews organize background, progress, decisions, changes, and open questions, with links to source Events.
|
|
267
293
|
|
|
268
|
-
For “Where did we leave the project's technical plan?”, the agent can find the topic, read its overview, then retrieve
|
|
294
|
+
For “Where did we leave the project's technical plan?”, the agent can find the topic, read its overview, then retrieve specific Events to verify agreed choices and outstanding decisions.
|
|
269
295
|
|
|
270
|
-
**
|
|
296
|
+
**Dreaming helps organize an existing directory.** Users can start a dedicated agent from the directory page to review existing Events and overviews and adjust chapters, sections, Event membership, and overview content. Its progress can be viewed, paused, resumed, or terminated; saved changes remain preserved.
|
|
271
297
|
|
|
272
|
-
|
|
298
|
+
Dreaming organizes the directory and overviews without rewriting original Event facts or reinforcing memory through organization or reading. **The directory helps locate information; specific facts still need checking against their sources.**
|
|
273
299
|
|
|
274
300
|
<a id="persistent-profile"></a>
|
|
275
301
|
|
|
276
|
-
|
|
302
|
+
#### 3.5 Persistent Profile: user information needed in every conversation
|
|
303
|
+
|
|
304
|
+
The persistent Profile stores user information that should remain available, separately from Events retrieved by relevance and requests that apply only to the current answer:
|
|
277
305
|
|
|
278
306
|
| User statement | Where it belongs | When it is used |
|
|
279
307
|
| --- | --- | --- |
|
|
280
|
-
| “Use Chinese by default from now on” | Persistent Profile | Automatically supplied across
|
|
308
|
+
| “Use Chinese by default from now on” | Persistent Profile | Automatically supplied across sessions after being set |
|
|
281
309
|
| “This project has switched to pnpm” | Event memory | Recalled or retrieved for relevant questions |
|
|
282
|
-
| “Keep this answer brief” | Current conversation | Applies to this answer
|
|
310
|
+
| “Keep this answer brief” | Current conversation | Applies to this answer |
|
|
283
311
|
|
|
284
|
-
The word “remember” alone does not determine where information belongs. Explicit
|
|
312
|
+
The word “remember” alone does not determine where information belongs. Explicit user requests to change the Profile can be applied directly. Inferred Profile changes require the agent to state the proposed field and value and obtain user consent.
|
|
285
313
|
|
|
286
|
-
|
|
314
|
+
See the [plugin guide](docs/DSH.md) for Profile fields, location selection, and settings.
|
|
287
315
|
|
|
288
316
|
<a id="evidence-gate"></a>
|
|
289
317
|
|
|
290
|
-
###
|
|
318
|
+
### 4. Retrieval and the evidence gate: find relevant information, then check whether it answers the question
|
|
319
|
+
|
|
320
|
+
When the available context is sufficient, the agent can answer directly. When historical information is needed, it searches Events or original conversations, or browses the topic directory first. With the knowledge graph enabled, it can also search entities and relationships.
|
|
321
|
+
|
|
322
|
+
**Retrieval can be enhanced as needed.**
|
|
323
|
+
|
|
324
|
+
| Method | Purpose |
|
|
325
|
+
| --- | --- |
|
|
326
|
+
| Default retrieval | Find relevant records using keywords and related signals |
|
|
327
|
+
| Vector retrieval (optional) | Add semantically similar Events even when their wording differs |
|
|
328
|
+
| Reranking (optional) | Reorder automatic-recall candidates so more relevant memories enter context first |
|
|
329
|
+
|
|
330
|
+
Vector retrieval and reranking are configured separately and remain off when unconfigured. Reranking applies only to automatic recall and falls back to the original order on timeout or error. **A high rank, semantic similarity, or high memory weight does not establish factual accuracy or sufficient evidence for the current question.**
|
|
291
331
|
|
|
292
|
-
|
|
332
|
+
**An empty result does not prove that something was never recorded.**
|
|
333
|
+
|
|
334
|
+
Empty results may reflect the selected memory scope, keywords, or filters. The agent should adjust its search to the question rather than conclude “you never said that” from a single empty result. Retrieval errors should also be reported as such.
|
|
335
|
+
|
|
336
|
+
**The evidence gate checks whether the information answers the question.**
|
|
293
337
|
|
|
294
338
|
For “Why did we originally switch to pnpm?”:
|
|
295
339
|
|
|
@@ -297,13 +341,11 @@ For “Why did we originally switch to pnpm?”:
|
|
|
297
341
|
| --- | --- | --- |
|
|
298
342
|
| Locate the topic | An overview of “Project technology choices” mentions a package-manager change | Follow the sources to specific Events |
|
|
299
343
|
| Retrieve the Event | “The project switched from npm to pnpm” | The change is established but its reason is missing; expand the source |
|
|
300
|
-
| Check the original text | Example: “Installation is faster, and it better fits our multi-package structure” | Verify the project and time, then explain the reason
|
|
344
|
+
| Check the original text | Example: “Installation is faster, and it better fits our multi-package structure” | Verify the project and time, then explain the reason from the source |
|
|
301
345
|
|
|
302
|
-
The quote is an illustrative example. If the sources do not explain the reason, the agent should state that it cannot confirm it
|
|
346
|
+
The quote is an illustrative example. If the sources do not explain the reason, the agent should state that it cannot confirm it rather than infer the historical decision from pnpm's general advantages.
|
|
303
347
|
|
|
304
|
-
The model assesses sufficiency; code checks source references and retrieval
|
|
305
|
-
|
|
306
|
-
Explicit retrieval batches must complete assessment and usage recording before the final answer; unused batches are closed with an empty usage record. If this is omitted, the plugin requests completion first, then a complete user-facing answer, so internal status does not become the final reply. The model can still misjudge evidence; uncertainty should remain explicit when verification is unavailable.
|
|
348
|
+
The model assesses sufficiency; code checks source references and the retrieval protocol. Explicit retrieval results must complete assessment and usage recording, including closing out results that were not used. Insufficient evidence calls for further retrieval; uncertainty should remain explicit when verification is unavailable.
|
|
307
349
|
|
|
308
350
|
<details>
|
|
309
351
|
<summary>Evidence assessment fields and protocol checks</summary>
|
|
@@ -322,33 +364,29 @@ References must belong to the selected retrieval batch. Accepting `sufficient` r
|
|
|
322
364
|
|
|
323
365
|
<a id="use-only-reinforcement"></a>
|
|
324
366
|
|
|
325
|
-
###
|
|
367
|
+
### 5. Memory reinforcement: retrieval does not reinforce; recorded adoption updates weights
|
|
326
368
|
|
|
327
|
-
|
|
369
|
+
An Event's weight participates in later recall and ranking. Without adoption, it gradually decreases as conversation turns accumulate, while the Event and its sources remain preserved. This differs from a conversation Block changing its L0–L5 display level.
|
|
328
370
|
|
|
329
371
|

|
|
330
372
|
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
**Retrieval does not trigger reinforcement.**
|
|
373
|
+
**Retrieval or display alone does not trigger reinforcement.**
|
|
334
374
|
|
|
335
|
-
|
|
375
|
+
Search hits, automatic context inclusion, directory browsing, overview expansion, and daily-note reads do not increase adoption counts or reset decay anchors merely because content appears.
|
|
336
376
|
|
|
337
|
-
|
|
377
|
+
**Events actually used in the answer receive that adoption's reinforcement.**
|
|
338
378
|
|
|
339
|
-
|
|
379
|
+
After choosing evidence for the final answer, the agent records its use. Code checks the retrieval batch and assessment result, then increases the corresponding Events' adoption counts and updates their decay anchors while preventing the same operation from being applied twice. Unused results receive no reinforcement from that operation.
|
|
340
380
|
|
|
341
|
-
|
|
381
|
+
More adoptions mean slower future decay, allowing memories that repeatedly help answer questions to retain higher recall priority.
|
|
342
382
|
|
|
343
|
-
|
|
383
|
+
**Confirmed duplicates during active-memory recording can also reinforce existing facts.**
|
|
344
384
|
|
|
345
|
-
|
|
385
|
+
When the active-memory tool saves information, a currently valid fact whose normalized full text matches exactly can directly reinforce an existing record. Other similar content requires further judgment to add, merge, supersede, flag a conflict, or ignore; textual similarity alone does not directly trigger reinforcement.
|
|
346
386
|
|
|
347
|
-
|
|
387
|
+
Duplicate-card organization also differs from answer adoption: a merge can preserve both records' existing adoption information, but does not count the organization operation as a new answer adoption.
|
|
348
388
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
**Different criticality levels have different minimum weights.**
|
|
389
|
+
**Different memory categories retain different minimum weights.**
|
|
352
390
|
|
|
353
391
|
| Memory category | Default minimum weight |
|
|
354
392
|
| --- | ---: |
|
|
@@ -357,9 +395,9 @@ When `memory_remember` records information, a confirmed exact or near duplicate
|
|
|
357
395
|
| Identity information | 0.9 |
|
|
358
396
|
| Safety information | 1.0 |
|
|
359
397
|
|
|
360
|
-
Pinned memories have an effective weight of 1. Superseded Events normally receive a low weight cap
|
|
398
|
+
Pinned memories have an effective weight of 1. Superseded Events normally receive a low weight cap, reducing the priority of older states.
|
|
361
399
|
|
|
362
|
-
These weights
|
|
400
|
+
These weights manage recall priority, not factual accuracy. Information that needs verification should still be checked against current state and its sources.
|
|
363
401
|
|
|
364
402
|
<details>
|
|
365
403
|
<summary>Long-term weight formula and counters</summary>
|
|
@@ -382,6 +420,37 @@ Long-term decay also uses conversation turns rather than elapsed wall-clock time
|
|
|
382
420
|
|
|
383
421
|
</details>
|
|
384
422
|
|
|
423
|
+
<a id="model-configuration"></a>
|
|
424
|
+
|
|
425
|
+
## Model configuration and upgrades
|
|
426
|
+
|
|
427
|
+
**Chat and memory processing can use different models.**
|
|
428
|
+
|
|
429
|
+
| Model purpose | What it handles | How to select it |
|
|
430
|
+
| --- | --- | --- |
|
|
431
|
+
| Chat model | Conversations and answers | Select in DSH |
|
|
432
|
+
| Memory-processing model | Conversation compression, Event extraction, topic organization, and Dreaming | Follow the chat model or specify a separate model |
|
|
433
|
+
| Embedding model (optional) | Find semantically related Events | Configure separately |
|
|
434
|
+
| Reranking model (optional) | Reorder automatic-recall candidates | Configure separately; usable independently of vector retrieval |
|
|
435
|
+
|
|
436
|
+
Under **More → Advanced settings → Host configuration → Memory-processing model**, choose to follow the chat model or specify a separate model. Saving applies the choice to subsequent memory-processing requests without changing the main chat model. Requests already running continue to completion.
|
|
437
|
+
|
|
438
|
+
The memory-processing model uses providers and models already configured in DSH. A model with tool-calling support and sufficient context capacity is recommended. If the specified model is unavailable, the task retains its failure state rather than automatically switching to the main chat model.
|
|
439
|
+
|
|
440
|
+
**Enable vector retrieval and reranking separately.**
|
|
441
|
+
|
|
442
|
+
In advanced settings, enter each service's API URL, key, and model, then save. A service is enabled only when its configuration is complete; clear its URL and save to disable it.
|
|
443
|
+
|
|
444
|
+
The embedding model supplements semantic matching, while the reranking model refines automatic-recall order. Neither replaces Event sources or the evidence gate's assessment.
|
|
445
|
+
|
|
446
|
+
When enabled, the search text and Event titles and summaries (candidate Event content for reranking) are sent to the selected service provider and may incur API charges.
|
|
447
|
+
|
|
448
|
+
**Restart the corresponding DSH profile after upgrading.**
|
|
449
|
+
|
|
450
|
+
The current version covers DSH **0.2.x**, including prereleases, and retains previously supported older hosts. DSH **0.3.x** is not yet supported. See the [plugin guide](docs/DSH.md) for the complete version range, older-host repairs, and recovery procedures.
|
|
451
|
+
|
|
452
|
+
Conversation sources and long-term memories are stored in local SQLite, while daily notes are separate Markdown files. Uninstalling the plugin does not automatically delete this data.
|
|
453
|
+
|
|
385
454
|
<a id="external-memory-import"></a>
|
|
386
455
|
|
|
387
456
|
## Import memory from another AI
|
|
@@ -392,24 +461,13 @@ The DSH UI previews the import. Duplicates can be ignored; changes can add, merg
|
|
|
392
461
|
|
|
393
462
|
See the [external-memory import guide](docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md) for formats, prompts, and integration examples.
|
|
394
463
|
|
|
395
|
-
## A real retrieval path
|
|
396
|
-
|
|
397
|
-
One LoCoMo question asks when Caroline gave a speech at a school:
|
|
398
|
-
|
|
399
|
-
1. Event search finds the “school speech” card, but it lacks the date.
|
|
400
|
-
2. The agent judges the evidence partial, identifies the missing date, and searches source messages.
|
|
401
|
-
3. It finds a message dated 2023-06-09 containing “last week.”
|
|
402
|
-
4. The message timestamp gives context for “last week,” providing enough temporal evidence to answer.
|
|
403
|
-
|
|
404
|
-
The Event helps locate the discussion, and the original message and timestamp support verification. The evidence gate requires the agent to identify the gap and keep checking.
|
|
405
|
-
|
|
406
464
|
<a id="experimental-results"></a>
|
|
407
465
|
|
|
408
466
|
## Evaluation results and limits
|
|
409
467
|
|
|
410
468
|
The repository's published R8 comparison uses the LoCoMo conversation sample `conv-26`, containing **419 messages, 35 sessions, and 152 questions** across categories 1–4.
|
|
411
469
|
|
|
412
|
-
**The
|
|
470
|
+
**The following results come from the published R8 evaluation. See the [evaluation document](docs/EVALUATION.md) for the tested version, models, and retrieval configuration.**
|
|
413
471
|
|
|
414
472
|
Each system generated answers, and each answer received **10 independent Judge evaluations**. These are repeated evaluations, not ten complete system runs.
|
|
415
473
|
|
|
@@ -424,7 +482,7 @@ Each system generated answers, and each answer received **10 independent Judge e
|
|
|
424
482
|
|
|
425
483
|
Both systems used the same questions, order, answer model, Judge model, evaluation prompt, parser, and evaluation count, and each rebuilt its memory. Memory extraction, retrieval implementation, embedding use, and answer context differed, so this compares two complete system configurations.
|
|
426
484
|
|
|
427
|
-
These results cover only `conv-26`, not the full LoCoMo dataset. They do not isolate the benefits of
|
|
485
|
+
These results cover only `conv-26`, not the full LoCoMo dataset. They do not isolate the benefits of conversation-memory display decay, the knowledge graph, or the evidence gate. Individual contributions still require ablation experiments.
|
|
428
486
|
|
|
429
487
|
See the [evaluation document](docs/EVALUATION.md) for the full protocol, per-question results, and Judge variation, and the [machine-readable results](benchmarks/locomo-conv26-r8-final.json) for summary data.
|
|
430
488
|
|
|
@@ -440,24 +498,6 @@ Within this evaluation, the results point to a need to improve when retrieval st
|
|
|
440
498
|
|
|
441
499
|
See the [full evaluation](docs/EVALUATION.md) for R1–R8 design history, per-question analysis, and further validation.
|
|
442
500
|
|
|
443
|
-
## Scope and costs
|
|
444
|
-
|
|
445
|
-
**Memory spaces determine which conversations share memories.** DSH defaults to project isolation based on the working directory. Session isolation and a shared global space are also available. Topics expose only visible Events in the current space; the persistent Profile is supplied across sessions and memory spaces. See the [plugin guide](docs/DSH.md) for configuration.
|
|
446
|
-
|
|
447
|
-
**Context budgets are not the total model cost.** Automatic recall and the topic directory have separate budgets. The persistent Profile, layered Blocks, unsealed conversation, and subsequent active retrieval are supplied separately. The 900-token recall budget and 400-token directory budget do not sum to a fixed size for the entire request.
|
|
448
|
-
|
|
449
|
-
| Stage | Does it call a model? | Where costs arise |
|
|
450
|
-
| --- | --- | --- |
|
|
451
|
-
| Background summaries, Event extraction, graph, topic and Profile organization | Yes | Conversation, Event or Profile inputs, generated outputs, and bounded retries |
|
|
452
|
-
| Reading an existing directory, overview, or stored search results | The read itself does not | Results still consume tokens when included in a later model request |
|
|
453
|
-
| Agent evidence assessment and answer generation | Yes | Current context, retrieved evidence, and generated answers |
|
|
454
|
-
|
|
455
|
-
Layered views reduce the history included by default when answering. For tool-heavy conversations, background derivation compacts code and oversized tool traces in model inputs while complete records remain in L5. Assess total cost from actual background, retrieval, and answer usage; smaller context alone does not establish savings.
|
|
456
|
-
|
|
457
|
-
**Historical topics appear progressively after upgrading.** Existing Events are organized in background batches, so the directory may initially be incomplete. New or changed Events receive priority. Failed or pending organization retains Event entry points and ordinary retrieval remains available. Historical work uses a shared database-wide allowance, bounded retries, and restart recovery; it does not promise a fixed cost. See [topic maintenance (Chinese)](docs/MEMORY_TOPICS.zh-CN.md) for limits and recovery.
|
|
458
|
-
|
|
459
|
-
Directories and overviews can be rebuilt from valid sources. When a source changes, is forgotten, or is archived, outdated derived content is hidden before background rebuilding. Updated extraction rules apply to subsequent normal extraction rather than rewriting all historical Events. Functional tests check these workflows and constraints; extraction, categorization, and evidence judgment still depend on the model.
|
|
460
|
-
|
|
461
501
|
<a id="code-entry-points"></a>
|
|
462
502
|
|
|
463
503
|
## Development and documentation
|
|
@@ -483,6 +523,9 @@ npm run build
|
|
|
483
523
|
| [DeepSeek Harness guide](docs/DSH.md) | Installation, configuration, UI, memory tools, and recovery |
|
|
484
524
|
| [Memory directory and topic overviews (Chinese)](docs/MEMORY_TOPICS.zh-CN.md) | Chapters and sections, source tracing, background organization, budgets, and recovery |
|
|
485
525
|
| [Event extraction rules (Chinese)](docs/event-extractor.md) | Extraction decisions, scope, duplicates and historical relationships, and compatibility |
|
|
526
|
+
| [Dreaming directory organization (Chinese)](https://github.com/diqierjia/StrataGate-AgentMemory/blob/main/docs/dreaming-agent.md) | Organization scope, run controls, source protection, and recovery |
|
|
527
|
+
| [Optional knowledge graph (Chinese)](https://github.com/diqierjia/StrataGate-AgentMemory/blob/main/docs/knowledge-graph.md) | Defaults, enabling, pausing, disabling, and historical backfill |
|
|
528
|
+
| [Manual level selection (Chinese)](https://github.com/diqierjia/StrataGate-AgentMemory/blob/main/docs/user-operation-priority.md) | Content preview, application, insufficient capacity, and recovery |
|
|
486
529
|
| [Architecture](docs/ARCHITECTURE.md) | Layering, Events and graph, retrieval, evidence gate, weights, storage, and core APIs |
|
|
487
530
|
| [External-memory import](docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md) | Export format, import flow, and integration example |
|
|
488
531
|
| [Full evaluation](docs/EVALUATION.md) | Protocol, version history, failure analysis, and result scope |
|