StrataGate helps long-running AI agents remember across sessions without turning every remembered detail into an unquestioned fact.
中文说明 · DeepSeek Harness guide · Architecture · Full evaluation
Current public result: on LoCoMo conv-26, StrataGate averaged 80.46% across 10 independent Judge runs, versus 63.22% for Mem0 base. See the scope and protocol.
In plain words: StrataGate remembers what happened, keeps where it came from, and checks whether the recalled information is enough before an agent relies on it.
| What you need | What StrataGate does |
|---|---|
| Memory across sessions | Automatically stores completed conversations, decisions, preferences, and tool results |
| A small active context | Shows compact memory first and expands older history only when more detail is needed |
| Answers you can verify | Traces Events and graph facts back to the original messages and tool output |
| Fewer confident guesses | Uses an evidence gate to decide whether to answer, search again, or inspect the source |
| Local control | Stores DeepSeek Harness memory in a local SQLite database; no separate memory server is required |
| Path | Best for | Start here |
|---|---|---|
| DeepSeek Harness plugin | Users who want automatic, local-first memory with a visual Memory UI | Install stratagate-dsh |
| Core TypeScript library | Developers building a custom agent or memory integration | Library entry points |
| WorkBuddy adapter | Existing WorkBuddy integrations that use the legacy Element path | integrations/workbuddy |
If DeepSeek Harness is already installed, add StrataGate to the profile you use:
dsh plugin --profile web add stratagate-dshRestart that profile, then keep using DSH normally. StrataGate will capture completed main-agent turns, build searchable memory in the background, and expose its Memory UI under DSH Settings → StrataGate-AgentMemory.
By default, the database is stored at:
DSH_HOME/stratagate/memory.db
Removing the plugin does not delete the database. For screenshots, configuration, memory tools, and the exact automatic-capture rules, see the DeepSeek Harness plugin guide.
A long-running agent needs more than a way to “store more.” When it answers, it must retrieve evidence that is correct, complete, and verifiable.
Keeping only summaries can lose dates, qualifications, and original wording. Similarity search can return related material that belongs to a different event. Treating every search hit as useful memory can also create a self-reinforcing retrieval loop.
StrataGate designs long-term memory around four core problems:
| Common problem | How StrataGate handles it |
|---|---|
| History keeps growing and no longer fits in context | Store conversations as L0–L5 layered views; older memories default to shallower levels |
| A summary omits a date, exact wording, or qualification | Preserve the L5 source messages permanently, so every derived memory can return to its source |
| Search finds related material, but not enough evidence to answer | Use an evidence gate to judge sufficiency; if evidence is incomplete, change strategy, expand an event, or inspect the source |
| Frequently retrieved results keep reinforcing themselves | Update long-term weight only for memories that the final answer actually uses |
StrataGate is not designed to make an agent retrieve more on every turn. It is designed to make the agent know whether the current evidence is sufficient and where to look next.
The current public comparison covers LoCoMo conv-26:
- 419 messages;
- 35 sessions;
- 152 category 1–4 questions;
- 10 independent Judge evaluations per question.
| Metric | StrataGate | Mem0 base | Difference |
|---|---|---|---|
| Mean accuracy across 10 Judge runs | 80.46% | 63.22% | +17.24 percentage points |
| Majority-correct | 121 / 152 (79.61%) | 96 / 152 (63.16%) | +25 questions |
| Temporal | 74.86% | 34.59% | +40.27 percentage points |
| Single-hop | 89.29% | 75.14% | +14.14 percentage points |
| Multi-hop | 66.56% | 61.56% | +5.00 percentage points |
| Open-domain | 83.08% | 84.62% | -1.54 percentage points |
The largest difference is in temporal questions. This is consistent with StrataGate's design—explicit event occurrence times, preserved source timestamps, and raw-source verification—but it is not a single-component ablation, so the full gap cannot be attributed to one field or retrieval step.
Both systems used the same questions, order, answer model, Judge model, Judge prompt, parser, and repeat count, and both rebuilt memory from scratch. Their memory extraction, retrieval implementation, embedding, and answer context differed, so this comparison is between two complete system configurations.
This is a single-conversation comparison on conv-26, not a full LoCoMo score. For the complete protocol, per-question results, Judge variation, and artifact hashes, see:
The normal path is deliberately simple:
- Keep the source. Completed messages and tool results are stored locally before anything is summarized.
- Build smaller views. StrataGate creates layered summaries, Events that describe what happened, and graph facts that describe the current state.
- Search small records first. The agent starts with compact results and expands an Event, graph node, or source Block only when it needs more detail.
- Check before answering. The evidence gate decides whether the result is sufficient. If not, the agent searches again or returns to the original messages.
- Reinforce only what helped. A memory gains long-term weight only after the final answer actually uses it.
For example, if a user says “Use pnpm for this project,” StrataGate keeps the original turn, creates a traceable Event, and can later expose “the project uses pnpm” as compact context. If an answer depends on the exact wording or surrounding discussion, the agent can expand that Event back to the source instead of trusting the shortened version alone. See a complete retrieval example.
By default, every 12 complete conversation turns are sealed into one memory block. Messages that have not yet reached the boundary remain in the open tail and are not compressed or extracted early.
This is the core-library default. The DeepSeek Harness plugin defaults to 6 turns per Block so Event extraction becomes available sooner, and exposes blockTurnSize as a user setting. Block age is the distance from the latest sealed Block in the same thread, so open-tail turns do not cause decay. The default Block-decay coefficient is 0.30.
Each sealed block contains six levels of detail:
| Level | Contents | Primary use |
|---|---|---|
| L0 | Title and tags | A lightweight index for distant memories |
| L1 | Short summary | Quickly judge whether a piece of history is relevant |
| L2 | Key facts | A compact factual list |
| L3 | Deterministically pruned conversation | Remove narrowly defined redundancy without free-form semantic rewriting |
| L4 | Readable near-verbatim conversation | Verify natural-language context and tool results |
| L5 | Complete messages and tool records | Final source |
New blocks start at L5. As more conversation follows, the default displayed level becomes progressively shallower; deeper detail can be expanded again when needed.
L0–L4 are derived views of the same source. They never overwrite or rewrite L5. Event cards likewise reference their source blocks and cannot modify them.
This lets StrataGate satisfy two goals at once:
- old memories remain lightweight;
- every important conclusion can still be verified against the original messages.
Decisions, preferences, plans, corrections, and temporal events that are worth finding later are organized into event cards.
Each event card stores more than a summary:
{
sourceBlockId,
sourceMessageIds,
mentionedAt,
happenedStart,
happenedEnd,
status,
participants,
eventType,
supersedesEventIds,
conflictsWithEventIds
}In this structure:
mentionedAtis when the event was mentioned in the conversation;happenedStart/happenedEnddescribe when it actually happened or is expected to happen;statusdistinguishes completed, planned, cancelled, and ongoing events;supersedesEventIdsandconflictsWithEventIdspreserve corrections and conflicts.
Separating mention time from occurrence time prevents the system from treating a message timestamp as the event timestamp. It also gives the system enough information to resolve relative expressions such as “last week” and “next month.”
Event extraction is delayed: after block N is sealed, precise extraction waits until block N+1 exists. The extractor can read neighboring blocks as context, but every new fact and source reference must come from target block N.
This reduces the chance that context is cut at a block boundary while preventing facts from neighboring conversations from being written into the wrong event.
Event cards preserve what happened. StrataGate can derive a current view of people, projects, organizations, tools, and places in two forms: legacy Element cards, or Graph Nodes and directed Graph Edges. The DeepSeek Harness integration uses the graph-native path; the WorkBuddy integration currently keeps the Element path.
Both projection paths run as independent, persisted jobs. A failed projection can be retried without extracting its Events again. A proposed fact or relationship is accepted only when its cited Events belong to the projection batch, so a derived claim cannot lose its source. State changes close or supersede the earlier derived fact without rewriting the Event that produced it.
searchEvents() and searchElements() combine deterministic BM25 lexical ranking with structured rankings for participants, types, names, and time; reciprocal-rank fusion combines those lists. searchGraphNodes() uses field-weighted BM25 across names, aliases, tags, state, facts, and relations. Searches return compact facts rather than entire large records, and a zero lexical match does not produce arbitrary candidates. The evaluated Event/Element path does not use vector or semantic retrieval.
A conventional retrieval system often hands several similar results directly to the answer model. StrataGate inserts a fixed protocol between retrieval and answering:
verdict · evidence_refs · fit · missing · next_strategy
After every retrieval, the system must answer five questions explicitly:
- is the current evidence
sufficient,partial, orwrong; - which results actually support that judgment;
- how the evidence matches the question;
- what is still missing;
- should the next step answer, continue searching, expand an event, or inspect the original messages.
The system accepts sufficient only when all of the following are true:
- at least one evidence item comes from the selected retrieval batch;
next_strategyis explicitlyanswer;- the judgment uses a fixed, bounded structure instead of an ever-growing private retrieval scratchpad.
If the judgment is partial or wrong, the system can choose:
search_events
expand_event
search_graph
expand_graph_node
search_elements
expand_element
search_raw_memory
expand_block
The evidence gate does not run the entire agent loop for the application. StrataGate supplies state, constraints, and validation; the integrating application still controls model calls, tool iteration, and the maximum retrieval budget.
An event being retrieved does not mean that it helped the answer.
Search therefore updates only observable retrieval records; it does not directly increase memory weight. After the answer is complete, the application explicitly calls:
await memory.recordMemoryUse({ eventIds, elementIds });Only Events, or the source Events behind adopted graph evidence, update their long-term weight. Legacy Element evidence remains supported by integrations that still use it.
This avoids a common feedback loop:
A memory happens to rank highly
↓
It is retrieved frequently
↓
Its weight keeps increasing
↓
It becomes even more likely to rank highly
A new event can supersede an old one, while the old event and its source remain available. Forgetting can remove an event from search without breaking the provenance chain.
importExternalMemory() can migrate a structured memory summary produced by another AI. The core API extracts candidate Events, compares each candidate with a bounded set of existing Events, and lets a model choose one of five actions: add, merge, supersede, mark a conflict, or ignore. Imported text is also retained as a permanent source Block, so every accepted Event remains traceable to the exact import.
The exported prompt and parser use the stratagate.external-memory.v2 format. Unknown dates remain unknown: the importer preserves the original temporal wording instead of guessing from the current date or message order. See docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md for the current integration guide.
The DeepSeek Harness UI currently provides a simpler direct-import flow: every valid candidate is added as a new Event. It does not yet run the core merge, supersession, conflict, or duplicate decision step.
One LoCoMo question asks when Caroline gave a speech at a school.
The event card found the “school speech,” but the card itself did not contain enough date information:
search_events
↓
Match the “school speech” event card
↓
The event is relevant, but has no exact date
verdict = partial
missing = occurrence date
↓
search_raw_memory
↓
Find the source message dated 2023-06-09
It says “last week”
↓
Resolve the relative date against the message timestamp
verdict = sufficient
↓
Answer
In this path:
- the event card provides fast location;
- the source timestamp and original message provide final verification;
- the evidence gate prevents the system from answering from incomplete information.
The current design was not decided in one pass. The most useful result of multiple experiments was not the round number, but the failure mode each round exposed.
| Problem discovered | Experimental observation | Final design choice |
|---|---|---|
| Temporal information was compressed into summaries and hard to recover accurately | In the early matched-protocol experiments, adding multiple events per block and explicit occurrence times raised Temporal from 18.92% to 45.95% | Separate mention time from occurrence time, and preserve the original temporal expression and source message |
| The agent's retrieval scratchpad kept growing | The bounded five-field evidence gate scored 77.63%; expanding it into a larger structured scratchpad reduced the score to 63.82% | Keep the judgment small and bounded, and let code validate its critical constraints |
| When evidence was insufficient, the agent repeatedly searched the same event cards | An early end-to-end version had 19 questions with at least three event searches and answered only 2 correctly; the current strategy answered 15 of the same questions, including 12 that inspected the source | Change information channels when search adds no new evidence instead of repeating the same search |
Compared with the earlier end-to-end version, the current version produced:
| Metric | Earlier version | Current version | Change |
|---|---|---|---|
| Mean accuracy across 10 Judge runs | 70.33% | 80.46% | +10.13 percentage points |
| Majority-correct | 107 / 152 | 121 / 152 | +14 questions |
| Retrieval rounds | 215 | 146 | -32.1% |
| Evidence-assessment calls | 237 | 146 | -38.4% |
| Total tokens | 6.69M | 4.09M | -38.9% |
These results show that repeated event search was a concrete failure path in the old version. Returning to the source when card evidence was incomplete improved both accuracy and retrieval efficiency.
However, the two end-to-end runs also differed in soft filters, Chinese-English synonym matching, result structure, and the freshly extracted memory state. This is useful diagnostic evidence, not a single-variable ablation of raw-source fallback.
For the complete R1–R8 experiment history, model and Judge changes, per-question transitions, and protocol boundaries, see docs/EVALUATION.md.
The current version still has 31 majority-wrong questions. Grouped by the final observable failure stage:
| Failure stage | Questions | Problem exposed |
|---|---|---|
| Answered directly without retrieval | 15 | Temporal, multi-hop, and list questions sometimes trust the model's own memory too early |
Evidence gate returned sufficient, but the final answer was wrong |
14 | Related material from a different event was accepted as sufficient, or a list answer was incomplete |
Evidence remained partial at the retrieval limit |
2 | Some questions genuinely did not retrieve enough evidence, but this is not the main bottleneck |
This indicates that the main problem is no longer “not enough retrieval rounds.” It is whether retrieval should start at all and whether the retrieved evidence truly supports a complete answer.
Next steps:
- freeze the memory state and separately ablate raw-source fallback, soft filters, and fact-level retrieval;
- provide gold evidence directly to the answer model to distinguish retrieval failure from answer-reasoning failure;
- repeat the same paired protocol across more conversations;
- finally expand to the complete LoCoMo dataset.
StrataGate is currently a research prototype for validating long-term agent memory designs.
The repository has implemented and validated:
- layered conversation blocks and their decay rules;
- event cards with provenance, time, and conflict relationships;
- independently retryable Element and knowledge-graph projection with Event-level provenance;
- BM25/RRF retrieval across Events, legacy Element facts, and Graph Nodes;
- structured external-memory import with permanent source preservation;
- isolated evidence assessment for concurrent retrieval batches;
- a bounded evidence gate whose constraints can be checked by code;
- a weighting mechanism that separates retrieval hits from actual answer use;
- automated tests, experiment records, and machine-readable evaluation results.
The public API, model integration, and evaluation coverage are still evolving. StrataGate should not yet be treated as a stable production SDK.
The default implementation uses in-memory state. The repository also provides an optional SQLite adapter for experimental-state persistence, interruption recovery, and consistency validation. It does not change the core retrieval semantics; see docs/ARCHITECTURE.md for the constraints.
Node.js 22 or later is required.
After checking out the repository locally, run:
npm install
npm run check
npm test
npm run buildThe main code and documentation entry points are:
examples/basic.ts: minimal code example;src/store.ts: core state, Block/Event/graph lifecycle, import, and retrieval;src/events.ts: stable Event-type normalization;src/elements.ts: provenance-checked element projection and time views;src/graph.ts: provenance-checked graph projection and graph state;src/external-memory.ts: external-memory schema, prompts, parser, and extractor;src/search.ts: deterministic BM25 token ranking and RRF fusion;src/retrieval.ts: evidence-gate normalization and constraint validation;src/blocks.ts: layering rules and deterministic pruning;docs/ARCHITECTURE.md: complete system boundaries and implementation invariants;docs/EVALUATION.md: complete experiment history and failure analysis.
examples/basic.ts demonstrates the core API; it does not fully reproduce the agent tool loop used in the benchmark. See the evaluation document for the model calls, tool orchestration, and Judge protocol used in the evaluation.
| Resource | Contents |
|---|---|
docs/ARCHITECTURE.md |
Data flow, layering rules, Event/Element protocols, retrieval, evidence-gate constraints, weighting, and storage invariants |
docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md |
External-memory export format, import flow, and integration example |
docs/EVALUATION.md |
R1–R8 experiments, model sensitivity, Mem0 comparison, failure analysis, and reporting boundaries |
benchmarks/locomo-conv26-r8-final.json |
Current result, per-stage statistics, run information, and source artifact hashes |
examples/basic.ts |
Minimal code example |
src/
blocks.ts Conversation layering, deterministic pruning, and level decay
events.ts Stable Event-type normalization
elements.ts Provenance-checked element projection and temporal views
external-memory.ts External-memory schema, prompts, parsing, and extraction
graph.ts Provenance-checked knowledge-graph projection
retrieval.ts Evidence-gate input, normalization, and constraint validation
search.ts BM25 lexical ranking and reciprocal-rank fusion
storage.ts Persistent snapshots and the StorageAdapter protocol
sqlite.ts Optional transactional SQLite adapter
store.ts In-memory state, lifecycle, import, and retrieval
types.ts Data structures and model-adapter interfaces
weights.ts Adoption records, forgetting, and weighting rules
tests/ Core-rule and storage tests
examples/ Minimal code example
docs/ Architecture and complete evaluation
benchmarks/ Machine-readable experiment results
Choose StrataGate when you want several of these properties together:
- automatic cross-session memory for completed conversations and tool results;
- local-first storage in SQLite, without deploying a separate memory service;
- project, session, or global isolation instead of one undifferentiated memory pool;
- layered Events and a knowledge graph that preserve both what happened and what is currently true;
- traceable recall that can expand a memory back to its original turns and tool output;
- an evidence-sufficiency gate before retrieved memory is treated as enough to answer.
Consider a different plugin first when the user's main requirement is free-form visual editing of memory records, hosted multi-user synchronization across products, or a minimal manually maintained notes file. StrataGate includes a read-oriented knowledge-graph view, but it is optimized for automatic, local, evidence-traceable memory rather than collaborative knowledge-base editing.
For DeepSeek Harness, follow the quick start. The DSH-specific behavior, tools, configuration, and failure semantics are documented in integrations/deepseek-harness.
StrataGate is available under the MIT License.