DEV Community: liuyuyan6100

06 — Chat Works. Does the Agent Actually Retrieve Memory?

liuyuyan6100 — Tue, 22 Sep 2026 00:03:16 +0000

The images in this article are explanatory diagrams with Chinese labels, not screenshots of test results. Each caption summarizes the diagram in English.

I wanted to make projects easier to resume across conversations and agents. Before testing whether the next agent could pick up where the previous one stopped, I checked something more basic: could it actively retrieve memory?

In the Docker deployment I was investigating, retrieval requests timed out while ordinary conversation continued. That combination was easy to misread. The assistant still answered, and memory content appeared in its context. Neither observation proved that its retrieval tools worked.

A successful conversation validates only part of the system

Chat and tool execution involve different requests. A working conversation showed that the client could communicate with the gateway. It did not establish that the client's tool execution environment could reach an address supplied inside a tool prompt.

The responsibility split matters: the model chooses a tool; the agent client's execution environment sends the request. A sensible tool choice can therefore produce a network failure. Debugging the model's decision alone will not reveal where that request actually went.

Figure 1: A simplified architecture diagram, rearranged from an existing Archify diagram. The chat connection and client-executed tool requests need separate checks.

Memory in context is not proof of retrieval

The proxy has two paths that share configuration and injection machinery but can succeed or fail separately.

Passive injection reads memory content or indexes on the server side and includes them in the context. This can include L3 core memory, L2 scenario indexes, persona information, and a skill list. In this deployment, passive injection continued to work.

Active retrieval supplies endpoints through tool prompts. The client then requests addresses such as ${base}/memory-bridge/v3 and ${base}/skill-bridge/v3/skill. This depends on the client being able to reach the generated address.

That explains how context could contain memory while retrieval failed. The server's read path worked; the URL handed to the client's tool executor did not.

The failure was also easy to miss in the conversation. Tool requests timed out or produced no HTTP response, recorded as 000. The assistant continued with file reads and local searches, without presenting a visible tool error to the user. I did not measure how much this fallback affected answer quality.

Figure 2: Passive injection can supply context even when active retrieval fails. A plausible answer is insufficient evidence that the retrieval path succeeded.

The missing setting was the injected gateway address

Following the failing path led to the URL-generation logic.

In the feat/server_team source I checked on September 19, 2026, injection.externalGatewayUrl takes precedence when configured. If it is absent and the configured host is 0.0.0.0 or 127.0.0.1, the fallback selects the first non-internal IPv4 address and builds an http://<host>:<port> base URL. It also emits a warning.

My Docker deployment had taken that fallback. The selected address belonged to the deployment's container network, while the client's tool execution environment was outside that network. Retrieval requests consequently timed out or received no HTTP response.

The missing piece was an existing configuration field. The source already documented explicit configuration for multi-node deployments; this was a deployment mistake, not a newly discovered upstream vulnerability.

Two useful starting points are the startup warning and the address actually injected into the tool prompt. Comparing that address with the client's gateway configuration can expose a discrepancy. A discrepancy still needs investigation: different addresses may be intentional, so test from the environment that executes the tool.

Interpret the probe before changing configuration

Two probe results deserve careful reading:

401 means an HTTP service responded and requires authentication. It does not demonstrate a successful memory operation, or establish by itself that this is the intended service.
000 means the probe received no HTTP response. It is not an HTTP status code identifying one cause. Timeouts, DNS resolution, and routing still need examination.

For the gateway, the proposed configuration change is straightforward:

injection:
  externalGatewayUrl: "https://gateway.example.com"

The domain above is a placeholder. The real entry point must be reachable from the tool execution environment, and the reverse proxy must forward the relevant bridge paths. The source handles a trailing slash; reachability and routing are the consequential checks.

I also need to change the persistent configuration source. Editing a file regenerated by a startup script would make the correction disappear on the next run.

Knowledge resources have their own URLs

Another failure in the same investigation had a separate cause. Tools for resources such as a wiki or code graph use URLs stored when those resources are registered. The injector copies those resource URLs.

Changing externalGatewayUrl does not update independently registered knowledge-resource addresses. Each one needs its own check.

The example in my notes used host.docker.internal. That name is a Docker Desktop convention; in a Linux environment without corresponding configuration, it may not resolve. The useful question is whether the name resolves and connects from this particular tool execution environment.

These failures pointed to injected addresses and name resolution. They did not establish that memory storage was damaged.

Figure 3: Memory and skill bridge addresses use the gateway base URL. Knowledge tools use their individually registered resource URLs. Fixing one source does not fix the other.

The verification I still need to finish

I have the diagnosis and a proposed correction. The post-fix checks are still pending. My next steps are:

Probe from the actual tool execution environment. Confirm that the injected address is reachable and routes to the intended gateway.
Update persistent configuration and start a fresh conversation. Inspect the newly injected tool addresses and confirm they no longer come from the unwanted fallback.
Make an authorized memory-tool request. Verify application-level success and content from the expected source, rather than inferring success from a later answer assembled through local search.
Test each registered knowledge-resource URL independently. Check resolution and connectivity, then retrieve an expected item and confirm its source.

Figure 4: My planned post-fix verification checklist. These steps have not yet been completed.

Only after those checks will I evaluate recall quality and cross-agent handoffs. Otherwise, I could spend time judging “memory” while the assistant is quietly using a different source. First I need to establish that retrieval actually happened.

References

My blog: Aiclaw — AI learning notes.

05 - After Wiring Up TencentDB Agent Memory, Why I'm Still Reading About Mnemosyne OS

liuyuyan6100 — Tue, 22 Sep 2026 00:03:02 +0000

Cover: accumulated project experience leading into the next handoff. AI-generated concept illustration.

A note before we start: all five diagrams below carry Chinese labels; the English captions summarize what each one shows.

The draft that made me restate the question

In the previous post I finished digging into DSH's plugin loading — DSH being the agent environment I've been working in across this series. Installing a plugin requires a restart; changing user configuration hot-reloads. They touch different layers.

That post left two threads open: build a plugin myself, and go deeper on memory integration. I said I'd write whichever produced something worth telling first. This time it's memory — but the trigger was a draft that came back wrong.

I handed my reference material to WorkBuddy and asked for a draft combining my recent study of TencentDB Agent Memory with ideas from Mnemosyne OS. It came back fast. The concepts were all there. There was even a table. It read like the real thing.

The further I got, the more something felt off: it knew the topic "memory systems," but it didn't pick up why I had arrived there.

The research from posts 01–04 receded into background. The structure of the reference article became the spine instead. Somebody else's experience got rewritten in the first person as "mine."

I wanted post 05. What I got looked like a brand-new opening with little connection to what came before.

That pushed me to restate the question: after all this time spent on agent memory, what exactly do I want the AI to remember for me?

From "the tool can be called" to "the project can be continued"

Looking back, the first four posts were all heading the same way.

In 01 I studied TencentDB Agent Memory: how conversations settle into memory, how docs and code become reusable assets. In 02 I went to DSH's source to understand how an agent environment carrying those capabilities is organized.

In 03 I connected the two — proxies, addresses, tool calls, debugging layer by layer until the integration ran. In 04 I went further into plugins: how capability gets installed, how config takes effect, why some updates force a restart.

Figure 1: This post continues the memory thread left open in 04 and pushes toward "how does a project get handed over."

Post 03 had a moment I keep thinking about: the code graph was already built, but allocation reported the resource didn't exist — asset registration hadn't been completed. Finished content doesn't mean the downstream consumption path works.

So the "integration" road has moved forward. But in day-to-day work another need kept getting sharper:

When I switch sessions — or switch agents — can work continue along the path the project already walked?

Take this article. A successor should at least know which problems the earlier posts covered and which step this one moves forward; which conclusions came from my own hands-on work and which from official documentation; what the reference articles inspired, and which narratives must not be passed off as my experience.

Knowing that I've "been researching memory lately" is nowhere near enough. It has to take that context and produce the right next action.

To be clear: this off-target draft was not a controlled comparison of memory products. I'm not claiming anything about which system recalls better. It just forced me to say my own requirement out loud.

Tencent line: integrated. Mnemosyne OS: still an open question

Keep the two tracks separate.

TencentDB Agent Memory — I've done real integration and debugging with it in the DSH scenario. Its official documentation explicitly puts memory storage, retrieval, and the access relationships between users, teams, and agents at the center of the product. [1]

Mnemosyne OS — so far I've only read GCat's article about it. I have not independently verified it on the same kind of task.

What caught my attention in that write-up is that it stores raw material and the index of descriptive material separately, and exposes precise location lookup, category lookup, and semantic search. [2] Whether the implementation actually delivers on that description in practice is something I have not yet verified on my side.

The description maps onto something I need when writing: a summary helps me recall a conclusion quickly, but when I actually quote a number or confirm an operation, I need to get back to the material. A findable summary should also be able to walk me back to where the evidence lives.

Figure 2: the verification path I want a successor to walk. This is a usage flow I'm proposing, not an architecture diagram of any product.

Reading this, I added one more question for myself:

When the project has already changed, is the memory the AI retrieves still fit to guide today's action?

"Found relevant content" is only the starting point. Next comes judging which project and which phase it applies to, and whether it has since been corrected.

I once used a certain development approach and later changed it. The old record still has value — it explains why things were done that way. But if a new session acts directly on the old record, it drags the project backwards.

That's why I'm still reading about Mnemosyne OS: I want to follow the thread of how memory is organized and retrieved, and make my own handoff problem concrete.

I already hit this need while building my workbench

Recently I've been turning my content workbench into a platform that can run on its own.

When I first wrote the requirements, one thing mattered a lot: it must own its own flow, be easy to operate, run independently, and not depend on any single agent.

Concretely: articles, revisions, publish tasks and execution results live in the application. When a scheduled task runs and what state it's in is managed by the service. A model can help with writing, but if I turn that off, content management and publishing should still work.

Finishing that let me separate two questions I'd been conflating:

One: does the program persist enough business state?
Two: can a later agent understand that state — and the reasons it came to be?

The workbench already persists articles, tasks and logs. That is not the same thing as "cross-agent long-term memory achieved." Whether a successor can read, understand, and correctly use those records still has to be verified on its own. That gap is what I want to close.

A recycle bin makes "remembered" concrete

The workbench recently got delete, restore, and batch cleanup for its publish queue. Small feature, but a good probe for whether memory is actually useful.

Say I move a not-yet-executed publish schedule into the recycle bin, then restore it.

An agent that only retrieves "the user once asked to publish this article" may conclude the task isn't finished and should be completed.

But the rule in the current workbench is: moving a pending schedule into the recycle bin cancels it; restoring the record keeps it cancelled and does not trigger a re-publish.

So at least three things have to be read together:

Figure 3: the workbench's current behavior, illustrated with an example task. "Restoring a record" and "publishing again" are two different actions.

Created a schedule, later cancelled, later restored — all three can be true at once. The question is which statement describes the past and which one governs the present.

Same with published content: clearing a local queue record does not mean the article was retracted from the platform.

If an agent reads "record deleted" as "article not yet published" and helpfully re-publishes it, then a more eager memory produces a bigger mess.

So for stateful business objects like publish tasks, I want a successor to check the current record first, then the execution receipts and history. Background material helps understanding; the final action still has to obey the state rules in the application.

History should explain the present. Current state should also be able to block the wrong action.

That tells me more about whether a system works than memorizing another set of memory terminology.

Requirements docs set direction; project memory has to carry the changes

I also read a WorkBuddy development tutorial by Eric (网瘾中年 Eric), which walks from rapid prototyping to clarifying requirements, splitting tasks, and writing acceptance criteria. [3] The method I took from it is plain: write down what to build and how far to take it before letting the AI start.

Applied to my own projects, I want to add one step: when a requirement changes, record the change and the reason.

A project might start out allowing automation inside the dev tool; later I explicitly require standalone operation. Hand the next agent only the earliest plan and it may happily reinstall a dependency I deliberately removed.

So I'm going to write a short handoff page for each ongoing project. For the workbench it would read something like:

What it should become: a personal content platform that runs standalone.

What to protect while continuing development: the model powers optional writing assistance; the core flow belongs to the application. Restoring a cancelled publish record must not resend it; clearing queue records must not delete drafts or published content.

Where to find the evidence: the current implementation, acceptance records, and the corresponding change notes; go back to the raw material when something needs checking.

Figure 4: the handoff method I plan to validate next. It is not wired up automatically yet — the page supplies context; current task state still has to be confirmed inside the application.

This handoff page is something I intend to try; it has not been wired into an automatic memory flow yet.

It also shouldn't become another chat log stuffed with detail. Task state that changes often should be queried from the application. Only settled constraints, important trade-offs, and lookup entry points belong on the page.

Writing works the same way. The handoff for post 05 should include the through-line of 01–04, this post's question, where the source material came from, and which facts are verified. With that in hand, reference articles go back to being material for me to think with.

N+EN was suggestive, but decisions still need evidence

The N+EN idea in GCat's article caught my attention on one point: a business agent's output can first be submitted as a candidate, then organized and reviewed before becoming the conclusion everyone builds on. [2]

Worth borrowing. But dropping it into my workbench can't mean "add another model and it will naturally know who's right."

Whether a publish task actually executed is answered by records and receipts. Whether a restored task may re-publish is answered by product rules and the user's decision. Whether a passage is my own firsthand experience is answered by going back to the source material.

A model can help organize that evidence. The hard part is writing down which evidence is sufficient and which cases need a human call.

The bad draft gave me a ready-made counter-example: it presented official PersonaMem benchmark results as "my own testing." Even if the numbers had been copied correctly, the attribution would already be wrong.

And if that sentence gets summarized into long-term memory, every future article may cite it. What eventually sticks is an error record that grows more familiar the more it's used.

So what I want to preserve isn't just conclusions — it's where they came from and under what conditions they hold.

On the engineering side, review conclusions and database transactions also have to stay separate concerns. Judging which material is trustworthy does not replace concrete mechanisms like preventing duplicate writes and keeping versions.

Next: three small handoff experiments

I'm not ready to call any of this solved. I want to test it with three small tasks.

First: continue writing in a fresh session. Give the new session the same series handoff material and see whether it can state where the earlier posts left off and pose the question this one advances. The draft should also correctly separate firsthand experience, described material, and unverified ideas.

Second: continue building the workbench with a different agent. Give it the current code and the handoff page, add one small feature. Acceptance checks: did it reintroduce a dependency I removed, and did it break an existing business rule?

Third: deliberately feed it a stale record. Let it see both "a publish schedule was created" and "it was later cancelled," then watch whether it finds the current state, explains the change, and stops the action that shouldn't continue.

These three experiments are the homework I want to turn in next. After running them I can talk about what worked and where the handoff still breaks.

From post 01 to here, my question has been getting more specific. It started as: how does AI memory get stored. Then it moved to wiring tools, reading source, studying plugins. Now I want these capabilities to preserve a project's full backstory — so that next time, in a new session, I can start from "here's where I left off."

More notes from this series live on my blog: https://blog.aiclawonline.website/

References

[1] TencentDB Agent Memory, official MemoryCore documentation — used to check the stated responsibilities around memory, retrieval, assets, and access relationships. My DSH integration experience continues from post 03 of this series.
https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/README_CN.md

[2] GCat, "Multi-agent memory shouldn't be one shared brain: N+EN distributed transmission sync + a ready-to-use cognitive prompt." My understanding of Mnemosyne OS comes from this article; I have not independently verified its implementation. N+EN is cited as a reference idea.
https://my.g-cat.cn/experience/n-en-sync-memory.html

[3] Eric (网瘾中年 Eric), "A WorkBuddy product development tutorial even AI beginners can follow" (course material, 2026-09-11). I borrowed the method of clarifying requirements, splitting tasks, and setting acceptance criteria; I have not adopted any demo results from the material as outcomes of my own project. No public download address is included here.

Why Do DSH Plugins Need a Restart? Bundles, Patches, and Hot Reloading Explained

liuyuyan6100 — Sun, 13 Sep 2026 15:05:03 +0000

At the end of my previous article about connecting DSH to Agent Memory, I left myself two directions to explore: work through DSH's plugin loading and development process, or take the memory integration further. Whichever produced something first would become the next article.

This week, it is the plugins' turn.

Here is the answer I found in the source code: in DSH, installing a plugin and editing configuration are different operations. In the normal bundle installation path, a newly installed plugin belongs to a bundle layer. It will not be baked into the plugin list until the next startup, which is why a restart is required. The “save to apply” behavior described in the documentation reloads the user patch layer at the top of the stack. The two statements describe different layers. This article follows how I pulled those two mechanisms apart.

DSH is an extensible Agent tool runtime built on Cordis. System capabilities are split into pluggable plugins, and profiles, bundles, and patches determine the effective plugin list. If you are unfamiliar with it, article 02 in this series provides some background.

The reason for this detour was simple: I was still gathering material for the memory integration, while my plugin experiments had already produced a pile of questions. In the previous article, I described DSH as an “everything is a plugin” architecture. I believed it, and I had successfully installed and run a third-party plugin. But several things that happened during installation still did not make sense to me. This week, I went through the source to work them out.

Installing a real plugin raised questions before I could celebrate

The normal path for installing a third-party DSH plugin takes two steps:

pnpm dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0
# Press Ctrl+C, then restart
pnpm dsh web

Archify is a skill-only plugin for drawing architecture diagrams. After installing and restarting, I asked it to draw a runtime architecture diagram in a new session, and it worked. Its built-in doctor check also passed all thirteen checks.

So far, so good. But two things bothered me.

First, why was a restart mandatory? Without restarting, the plugin did not take effect. It was 2026, and a modern plugin system still needed a process restart after an installation?

Second, the documentation said that the web profile supported live reloading: edit the configuration file, save it, and the change takes effect. A mandatory restart on one hand, immediate changes on the other. Those statements seemed contradictory unless they referred to different things.

Following those two clues into the source led to a more elegant answer than I expected.

What “everything is a plugin” really means: the plugin list is baked

DSH is built on Cordis. I used to interpret “everything is a plugin” as “all functional modules are plugins.” That is true, but it misses a deeper part of the design.

The source shows that the plugin list DSH actually starts is not any single handwritten configuration file. It is the result of starting with an empty configuration and applying patches, layer by layer, in order. The layer-loading sequence is in packages/boot/app-boot/src/index.ts; that code also establishes the reloading boundary discussed later.

There are three concepts:

Entry: a plugin instance to start, represented as { id, name, config }.
Layer: a YAML patch file that adds entries to the list or modifies existing entries.
Bundle: an npm package that declares dsh.bundle. The patch file supplied by that package is the layer it contributes.

The layers baked into the web profile on my machine look like this:

Empty root configuration: []
  -> dsh-base
  -> dsh-web-app
  -> archify
  -> super-injector
  -> user patch: cordis.patch.yml (live HMR)
  -> --patch overlays (one-shot)
  -> final plugin entries

What I had thought of as “the plugin configuration” was actually a view produced by applying patch layers to an empty configuration in order. An official command can print this layered view directly. Each section includes a # == package-name source comment, making it clear which layer contributed which entries.

Three patch operations, with rules that matter

A layer is an increment, not a complete configuration. Patches from all layers are flattened into a list and applied in order. There are only three operations. The patch algorithm lives in applyEntryPatches in vendor/include/src/index.ts; the four rules below come from its code comments.

{ insert: [...] }: append new entries. This is the operation used when installing plugins.
{ id: target, ... }: find an existing entry by ID, then replace its configuration or disable it.
{ id: group, insert: [...] }: insert child entries into a group-type plugin.

Four rules are especially important.

Later layers can modify earlier layers. Patches run in order. An entry inserted by an earlier layer can be modified by ID in a later layer, so order determines precedence. The user layer sits above the bundle layers, which is why it can override a plugin package's default behavior. The one-shot --patch overlays shown in the diagram come after it.

Inserted entries enter the index immediately. This is easy to overlook but essential: a later patch in the same batch can target an entry that was just inserted. Without this behavior, entries inserted by bundles would be black boxes that the user layer could never configure.

A deep-copy snapshot is taken before each layer is applied. Layers do not share objects. Removing a patch can therefore restore the configuration below it cleanly. Rollback is part of the design, rather than an afterthought.

Malformed patches fail loudly; unmatched entries only produce warnings. A broken patch file causes a startup failure instead of letting the process continue with bad configuration. But a patch that does not match an entry only produces a warning and is skipped. One overlay may be shared by several environments, so it does not need to match something everywhere.

I like this distinction: fail as early as possible on invalid configuration, but be permissive about unmatched targets. One is an error; the other can be normal.

The earlier questions finally fit together

Once I understood the mechanism, I could explain the behavior that had confused me.

Why does installing a plugin require a restart? In the normal assembly path, layers are baked into the plugin list at startup. Once the process is running, it does not reread the contents of the bundle layers. Installing a new package or changing its version therefore requires a restart so that the list can be baked again.

Why does the documentation also say “save to apply”? Live reloading watches the two patch files in the user layer, above the bundle layers in the diagram. It uses transactional replay through Cordis HMR: hmr.registerConfig registers the watch; when a file changes, the configuration is reread and the entire layer is replayed. If that fails, the previous generation is retained. Only the user layer is reloaded. The bundle layers underneath remain unchanged. The two descriptions refer to different layers.

Step	Install or upgrade a bundle through normal assembly	Edit a user patch
Change	Install or upgrade the package	Edit the profile or home user patch file
Registration	Reconcile the layer catalog	The watch is registered through `hmr.registerConfig`
Apply	Restart the process and bake the layers again	Transactionally replay the changed layer
Result	The rebuilt plugin list takes effect after startup	Apply the new layer, or retain the previous generation on failure

This comparison concerns normal bundle assembly and user-configuration reloading. Runtime injection through super-injector is a separate path, described below.

Why does running dsh plugin automatically pick up a package installed manually with pnpm add? Reconciliation detects the package's dsh.bundle declaration and appends it to the layer catalog. This is deliberate behavior.

Why does an installed package sometimes produce only a warning and never activate? It has not declared dsh.bundle. Without contributing a layer, it is just an ordinary dependency.

Why does a restart produce duplicate loader entry id? Two layers have inserted the same entry. A typical case is a bundle registering its own entry while the user has also copied that entry into a user patch. Both layers have inserted exactly what they were told to insert.

This mechanism explained six of the seven pitfalls I had encountered. It felt good to have one model that explained the behavior instead of a list of conclusions to memorize.

Two development paths, depending on how often the code changes

With the mechanism clear, I returned to my original ambition: moving from using plugins to developing them. I found two development paths in the DSH ecosystem. The choice depends on how frequently the source changes.

The first is the official assembly path. A plugin is a TypeScript module with export const name and an apply(ctx) function that registers tools, events, and services on the context. For local development, link the package into the profile's node_modules using link:, then attach it with a patch file. Updates follow the installation method: change the version for a registry package, or replace the directory contents for a linked package. One detail matters when replacing a directory: remove the old directory before extracting the new one. Extracting over it can leave behind files that the new package removed, and those stale files may be loaded accidentally.

The second is runtime injection. On my machine, the resident super-injector makes this a hot-swapping workflow: generate a plugin skeleton, build a tgz, inject it into the running process, and hot-reload it without restarting. Failed hot reloads automatically roll back to preserve the old version. Unloading cleans up the fibers, and there is even a dedicated recovery command for orphaned routes left behind by hot reloads.

My choice is to use official assembly for finished plugins that I update with upstream releases, such as archify and super-injector itself. Upgrading takes one command. When I start writing my own plugin and reach the edit-and-try-again stage, I will switch to injection. Restarting after every change would quickly become exhausting.

Closing thoughts

This time, the result was not an impressive end-to-end demo. It was a model: the plugin list is baked, layer order determines precedence, and live configuration reloading happens only in the user layer. When I install another plugin or change configuration, I now have that layered diagram in mind.

As for developing a plugin myself, I have worked out the skeleton and the build process. What I still need is a real requirement to aim at. The next article will start with that plugin: registering the first tool through apply(ctx), declaring dsh.bundle, building a tgz, and injecting it into the runtime. I want to walk the whole path from source code to a plugin running inside DSH and report back whether it succeeds or fails. The memory integration is also moving forward. The rule remains the same: whichever direction produces something first gets the next article.

Environment used for this article: Windows 11 + WSL2, running DSH from a source checkout with pnpm dsh web, using the web profile. Relevant source locations: packages/boot/app-boot for layer loading, and vendor/include for the patch algorithm.

Wiring DSH Into TencentDB Agent Memory: Five Traps, Each With a Different Root Cause

liuyuyan6100 — Mon, 31 Aug 2026 15:19:44 +0000

I ended the last DSH piece with a promise:

Next I want to wire DSH up to the local TencentDB Agent Memory as a callable tool and get a real end-to-end scenario running. I'll write it up once it works.

It works now. Time to pay that debt.

It was not a smooth plug-in. It was five problems stacked on top of each other: a wrong model id, a network address that didn't exist, a proxy injecting an unreachable gateway, a model hallucinating an empty tool name, and a "knowledge base resource does not exist" ghost story. Every one of them taught me something about a different layer of the stack. Below is the order I actually debugged them in, not a tidy textbook order.

What I was trying to build

Let me set the target first so the rest makes sense.

I run DSH (DeepSeek Harness) from source on Windows. I wanted it to call a set of external memory tools during a conversation — searching past sessions, writing knowledge, querying a code graph. That memory system is TencentDB Agent Memory, running in Docker under WSL2, split across three containers:

tdai-proxy — model proxy plus the skill/memory injection gateway, port 8096
tdai-memory-hub — admin panel, 8125 / 8424
tdai-memory-core — identity, assets, memory storage, 8420

The integration mode is proxy mode: dsh doesn't talk to OpenAI or DeepSeek directly. It sends LLM requests to http://127.0.0.1:8096/dsh/default. Before and after forwarding upstream to a relay, the proxy injects <skill_tools> and <tdai_memory_tools> blocks into the system prompt so the model knows these tools exist; the actual calls then go back to the proxy's bridge endpoint.

Sounds like a one-line change to the API base URL, right? That's exactly what I thought, too.

Trap 1: the SSE stream just died

Right after changing the address, every turn failed with SSE stream ended without [DONE], error code STREAM_CLOSED.

My first instinct was that the proxy had crashed, but the container logs said it was healthy. So I hit the relay directly with curl and got this back:

{"code":"model_not_found","message":"No available channel for model deepseek-v4-pro under group 百炼国模"}

Alibaba's Bailian platform doesn't expose bare model aliases. Every snapshot is an independent id with a date suffix, something like deepseek-v4-pro-0813. The relay had no channel configured for deepseek-v4-pro, so it returned 503. dsh's SSE parser never received [DONE] before EOF and treated it as a truncated stream — that's by design, not a bug.

Editing ~/.dsh/settings.yaml fixed it: I swapped the id declared under llm-deepseek.models for deepseek-v4-pro-0813, pointed agent-default-model.model at the same thing, and the first turn went through.

That was only the first domino.

Trap 2: not enough balance, reported as "invalid API key"

With the model id correct, longer sessions started failing again. The dsh UI said "this turn failed: invalid API key", error code AUTH.

That wording is dangerously misleading. I nearly went off to rotate my key. The proxy logs told a different story — upstream had returned 403:

{"message":"预扣费额度失败, 用户剩余额度: ＄56.639376, 需要预扣费额度: ＄59.112000","code":"insufficient_user_quota"}

new-api freezes the worst case up front: (input tokens + output cap) × model multiplier × group multiplier. On this relay that works out to roughly $0.46 per 1K tokens of context, so a single 128K-context turn wanted close to $60 pre-authorized. Not enough balance, hence 403. dsh maps both 401 and 403 onto AUTH, which is how a quota problem turned into "invalid API key".

Worth noting: this isn't the real charge. After the request completes it settles against actual usage — a 128K turn really costs about $2.3 — but you still have to clear the pre-auth threshold first.

My stopgap was to keep context under 100K, which dropped the pre-auth below the threshold and let sessions continue. Longer term it's either top up, switch to a lower-multiplier channel, or actively manage session length.

The lesson I took from this: dsh's error text is only a local classification. For the precise cause, always read the proxy log or the raw upstream response.

Trap 3: the proxy injected an address Windows can't reach

With the LLM path working, I moved on to testing skill calls. The bridge address written into the <skill_tools> block was http://172.18.0.4:8096, and calls timed out immediately.

From the Windows side, curl 127.0.0.1:8096/skill/search returned 401 — a business response, meaning the service was alive — but curl 172.18.0.4:8096 gave me a flat curl 52 Empty reply from server.

This is the classic WSL2 half-open situation: the Docker bridge subnet 172.18.0.0/16 has no working return route to Windows. The TCP handshake appears to succeed, but the response never comes back. A container IP shouldn't be referenced from Windows in the first place, and it drifts on every restart anyway.

So the real question became: who writes that address into the injected block?

Reading the proxy source, the base URL decision in MemoryProxy/src/injection/index.ts is:

if injection.externalGatewayUrl is configured → use it
otherwise → fall back to the first non-internal IPv4 from os.networkInterfaces(), which inside a container is the Docker bridge IP

That fallback was designed for single-machine local development. Under Windows + WSL2 it picks an address that is unreachable from the side dsh runs on.

The worse part: start-proxy.sh unconditionally regenerates .proxy-config/config.yaml on every start, so hand-editing the output is pointless. The fix has to go into the generation template:

Add a line to the injection: section of the start-proxy.sh template: externalGatewayUrl: "${PROXY_EXTERNAL_GATEWAY_URL:-}"
Append to .env: PROXY_EXTERNAL_GATEWAY_URL=http://127.0.0.1:8096
Re-run the startup script and verify the generated file

This one re-taught me something I keep re-learning: when a config file is generated by a script, the fix belongs in the generation chain. Hand-editing generated output is planting a landmine.

Trap 4: the model called a nameless tool, and the parser believed OpenAI's format

Once the bridge address was 127.0.0.1:8096, skill calls went out — and dsh immediately reported unknown tool "". The tool name was empty.

This was the most instructive failure of the five. I bypassed dsh entirely, curl'd the proxy with the same headers, and looked at the raw SSE bytes coming back upstream:

chunk 1: tool_calls[0].function.name = "get_weather", arguments = ""
chunk 2: tool_calls[0].function.name = "",            arguments = '{"'
chunk 3: tool_calls[0].function.name = "",            arguments = 'city":"'

OpenAI's streaming convention puts the tool name only in the first chunk; continuation chunks leave the name field present but empty as a placeholder. dsh's parser in packages/llm/llm-deepseek/src/translate.ts, however, was written as:

if (call.function?.name !== undefined) block.name = call.function.name

An empty string is not undefined, so the correctly accumulated name got overwritten with "".

The official DeepSeek API simply omits the name field on continuation chunks, which is why this loose check never caused trouble before. But my upstream is an OpenAI-format relay, where the field exists and is empty — so it triggered instantly.

The fix is one line:

if (call.function?.name) block.name = call.function.name

I added a unit test alongside it, pinning the behavior with the exact data shape I captured.

This reinforces what I said last time: for streaming or protocol mismatches across services, always capture the raw bytes before you read the code. There's a proxy, an adapter, and a translation layer in between, and the logs at any one of them are already somebody's interpretation.

Trap 5: the graph is ready, but allocation says "resource does not exist"

The last one felt like a haunting. Memory Hub's Code_Graph page showed both repositories as Ready, but clicking "Assign to Agent" failed with 知识库资源不存在或已被删除 ("knowledge base resource does not exist or has been deleted") and a request_id.

I traced the call chain by request_id through the tdai-memory-hub and tdai-memory-core logs:

POST /api/v1/knowledge/allocate
  → /v3/meta/auth/verify            200
  → /v3/meta/team-member/get        200
  → /v3/meta/asset/get  cg-x7dg44vu → 404 asset_not_found

So the code graph itself lives in the knowledge service's own storage, and "Ready" on the page only means the graph was built successfully. But "Assign to Agent" validates against memory-core's asset registry, meta_asset. By design, once the graph finishes building, KS should call back into Panel, which then back-fills the asset registration — and that callback is best-effort. It doesn't block the build when it fails, which leaves you in a middle state where the graph exists but the registration doesn't.

Panel ships an idempotent backfill endpoint for exactly this. One call:

curl -X POST http://127.0.0.1:8125/api/v1/knowledge/code-graph/register-meta \
  -H "Content-Type: application/json" \
  -H "x-tdai-service-id: default" \
  -H "x-tdai-user-key: <sk-mem-...>" \
  -d '{"team_id":"team-a5bu20zsn8","code_graph_id":"cg-x7dg44vu"}'

Once per graph, returning registered: true, and allocation started working immediately.

The general lesson: when a component's "displayed state" and its "authoritative state" live in two different stores, a healthy UI doesn't mean validation will pass. Best-effort async registration needs an explicit compensation entry point.

What it feels like now

With all five resolved, dsh can finally call the memory tools mid-conversation. Not the cheap thrill of "changed a config and it worked" — more like the solid feeling you get when every layer's root cause lines up with the symptom above it.

The single move I relied on most across this whole debugging session: split the error into layers, then go read raw data one layer down. dsh's UI text, the proxy's log, the upstream response, the source code's conditionals — where those three agree, there's no bug; where they disagree, that's your bug.

I already wrote about DSH's "if the model can see it, it's recorded" principle and Cordis's plugin composition in the previous article. Wiring in a real external memory system made the value concrete for me: plugin architecture isn't just about swapping models, it's about plugging an entire memory system in as another Provider. And traceability isn't just logging — it's being able to peel the onion layer by layer instead of circling in front of a UI error message.

What's next? Two directions on the desk. One is walking DSH's plugin loading and development flow myself — last time I said everything is a plugin, and now I want to move from being a plugin consumer to a plugin developer, using a real requirement as the exercise. The other is pushing the Agent Memory integration deeper, so retrieval and writes become routine moves in a conversation rather than a single demo path. Whichever produces results first gets written up first.

原文发表于沐沐ai专题

关注「沐沐ai专题」公众号，获取更多 AI 实战干货

A Week Reading DSH's Source: The Two Rules That Won Me Over

liuyuyan6100 — Sat, 29 Aug 2026 15:17:26 +0000

Let me start with context, so this doesn't read like another piece of marketing copy.

I've been hacking on an agent project for a while, and while shopping for a foundation I went through several frameworks — some so opaque you can't debug them, others where swapping a model adapter means editing core code. Last month I needed something whose capabilities come apart cleanly and where every step can be replayed, so I dove head-first into DeepSeek's open-source DSH (DeepSeek Harness) and spent a week chewing through the source plus its docs/architecture.md and AGENTS.md.

This isn't a restatement of the official intro. It's my own notes after reading, running, and face-planting. Here's DSH's one-line philosophy up front:

Agent = Model + Harness
The model is the soul; the harness is the shell that actually plugs it into the environment — files, shell, search, skills, sessions, sandbox, scheduling, UI, all hanging off of it.

What actually won me over wasn't that one-liner, though. It was the two rules baked into its bones: everything is a plugin and every run is traceable. More on both below — everything here is verified by me.

What it actually is: an agent shell, not a chatbot wrapper

Start with what it is not: DSH is not another chatbot skin. It's a harness that wires a model into a real environment.

Underneath it runs on the Cordis kernel (github.com/cordiverse/cordis), and every capability lives on a node of a "plugin tree." I assumed that was just fancy talk for "everything is a component" — until I read the source and confirmed that the model, tools, skills, sessions, sandbox, storage, loop, scheduling, and UI are none of them hardcoded in the core. They're all composed from plugins and swappable from config, without touching DSH itself.

By capability count, DSH ships four shapes. Day to day I live in Standard and Code:

Standard — the full toolset: file editing, shell, search, skills, planning, subagents, workflows.
Code — built on Standard, but tools are exposed through the Code Mode SDK, so the model can orchestrate multi-step operations inside a single TypeScript program. Delicious for coding agents.
Minimal — the bare-bones shape with only persistent bash and str_replace_editor. This is for model benchmarks, not for your daily driver.
Creator — a workbench for authoring custom agent presets, with runtime checks and preset-writing guidance.

The two rules I only believed after reading the source

Both of these are shouted from the website and the README. But you only know they're real once you've tripped over them and gone digging.

Rule one: everything is a plugin

This is the most counterintuitive and the most elegant part. In other frameworks, swapping a tool provider or a model adapter usually means going spelunking through core code. DSH's core design is: capability seam = Service Definition + Service Provider + Consumer, and you need all three.

I specifically went to verify a claim that sounded exaggerated — that swapping out one fs provider moves the entire Bash / PTY / LSP stack into a remote sandbox. After reading how the plugin tree mounts things, it really is just: provide another Provider, point at it in config, and the capability moves. That's what "everything is a plugin" looks like as engineering: changing model, sandbox, or storage is a matter of changing one Provider, not a rewrite.

Rule two: every run is traceable

Model-visible ⟺ logged

Meaning: anything that reaches a model request — system prompts, reasoning, tool calls and results, subagent dispatch, context injection — must be reconstructible from a single append-only session log. In the Trajectory view you can audit each entry by source; resume, fork, search, and replay all ride on that same event stream.

In plain words: debugging an agent finally stops being guesswork. What it saw at each step, which tool it called, what came back — all of it is on the record. For an agent that's expected to keep working in a real environment, traceability isn't a nice-to-have; it's the engineering seatbelt. Without it you're stuck forever in the black box of "why did it get it wrong this time."

Getting started: two traps cost me half a day

Regular users need one line:

npx @deepseek-ai/dsh --profile web
# equivalent
npx @deepseek-ai/dsh web

If you want to modify source, clone it. I went the source route and tripped on step one:

git clone https://github.com/deepseek-ai/deepseek-harness
cd deepseek-harness
pnpm install
pnpm dsh web          # web is an alias for --profile web; source runs directly via tsx

There's no global dsh command in the source repo — you launch it with pnpm dsh <subcommand>. pnpm dsh web is equivalent to pnpm dsh --profile web, and it's currently the only profile with a dedicated alias.

Two traps I personally ran into, so you don't have to:

Cannot find module 'node:sqlite', or pnpm complaining it "requires at least Node.js v22.13" — your Node is too old. Use v22.19+ or ≥24; v20 is simply not enough, since it relies on newer modules.
Cannot find module '.../typert.host.js', or a startup error of client bundles not found — I had to run pnpm run build once (tsc emits lib/types, tsdown bundles the runtime) before it would come up. In theory pnpm dsh web runs source directly through tsx, but on a first run with missing client bundles, a build saves the day.

That's it — two traps, half a day gone.

Installing plugins: the "small thing" that wrecked me

DSH has no hot reload — plugin add only writes the plugin layer into the profile's on-disk config; a running server won't pick it up. So installing a plugin is a fixed sequence:

# 1) Ctrl+C the server first

# 2) install the plugin (works while the server runs, but nothing hot-loads)
pnpm dsh plugin --profile web add "github:NanmiCoder/dsh-auto-mode#main"
pnpm dsh plugin --profile web add "github:zhu1090093659/dsh-web-ui#main"

# 3) verify the bundle layer got mounted
pnpm dsh --profile web --dump-config

# 4) start it, with --patch (mandatory!)
pnpm dsh web --patch

Two hard-won lessons, learn them by heart:

Installing a plugin edits the on-disk config; a running server won't load it — you must restart. The first time I installed one, I went looking for the new feature in the UI and found absolutely nothing.
You must start with --patch. This is the one that really bites: plugin add reports success, but if you start without --patch, a bunch of plugins and skills simply won't activate — while everything still looks installed. Wasted effort.

To try a layer temporarily without installing it: npx @deepseek-ai/dsh web --patch ./cordis.patch.yml.

A few truths hiding behind those commands (confirmed by reading source and actually doing it):

dsh plugin --profile web add xxx isn't DSH installing a package itself — it forwards the remaining arguments verbatim to pnpm, equivalent to running pnpm add xxx inside the profile directory.
The profile directory defaults to ~/.dsh/profiles/<name>/ (on Windows: C:\Users\<user>\.dsh\profiles\<name>\). Using web as an example: after installing a plugin, new packages appear under dependencies in package.json, and dsh.profile.bundles registers a layer automatically — which is why --dump-config can see it.
If you install a marketplace UI entry (dshmarket), the entry isn't a standalone page — it lives under Settings → Plugin Marketplace. The host needs to be ≥ 0.1.0-rc.6 for it to show up.

Command cheat sheet:

# install / remove / inspect dependencies
pnpm dsh plugin --profile web add <package>
pnpm dsh plugin --profile web remove <package>
pnpm dsh plugin --profile web why <package>

# start different profiles
pnpm dsh web                              # alias for the web profile
pnpm dsh --profile headless "your task"   # headless, one-shot task

# inspect config
pnpm dsh web --dump-config                # fully composed config tree
pnpm dsh web --dump-default-config        # defaults, without your overrides

The plugin ecosystem: what I installed and how it feels

The marketplace is already busy. After installing dshmarket locally, the real marketplace shows up in DSH Local Builder's settings: dsh-market v1.24.0, with tabs for Discover / Themes / Installed / Advanced, and filters covering UI enhancement, themes & appearance, model & account access, tools & capabilities. The cards list things like dsh-web-ui-all, DSH-better-sidebar, modlens, dsh-vision-router, and dsh-vision-toolkit — all genuinely installable, not just names from docs.

Community plugins worth installing:

dsh-web-ui / dsh-web-ui-all — the full UI bundle: task board, Git graph, sidebar, terminal, token stats, skins. Installing this is a step change in how it feels.
dsh-auto-mode (strongly recommended) — manages safe automatic permissions for you, handling shell and file approvals far more safely than hand-editing global.json.
modlens (900+ stars) — gives plain-text models "eyes" by turning images into structured text.
dsh-agent-teams (898) — multi-agent collaboration.
dsh-memory (73) — cross-session memory; this is where an agent's recall comes from.

Then there are ZhijiangTang's 14 zero-config tool plugins, which I'd call the best textbook on plugin development around — each 100–500 lines, pure JS with no native dependencies, usable right after npm i. A few high-frequency ones:

dsh-safeguard — intercepts dangerous commands (rm -rf, push --force) and secret leaks (AKIA / sk- / ghp_) before execution. A life saver.
dsh-http — structured HTTP: status code, latency, size, Bearer/Basic auth, automatic JSON parsing.
dsh-fmt — JSON/YAML/TOML/SQL formatting and validation, with errors reported down to line and column.
dsh-handoff — one-click session export (decisions / done / not done / next steps).
dsh-password — strong password and diceware passphrase generation, with entropy annotated.

Install the whole bundle in one go:

dsh plugin --profile web add dsh-safeguard dsh-http dsh-case dsh-fmt dsh-clipboard \
  dsh-fetch-file dsh-jwt dsh-cron-parse dsh-pkg-info dsh-dead-links dsh-when \
  dsh-handoff dsh-url-tools dsh-password

There are also vendor bridge plugins, such as @wxg-prc-cpg/dsh-weknora (Tencent WeKnora knowledge retrieval: semantic search, document reading, RAG). Those wire an existing product into DSH — high star counts, but they're "bridges," not capabilities built from scratch. Don't confuse the two in your head.

Permissions: one line of advice — don't hand-edit

I can't state DSH's permission config file path with any confidence (sources online contradict each other, and I'm not going to invent it). But in my testing, just installing the dsh-auto-mode plugin is by far the least painful route — it manages shell and file approvals for you, far more reliably than hand-editing config:

pnpm dsh plugin --profile web add "github:NanmiCoder/dsh-auto-mode#main"

Want to write your own? Here's the shortest path

I'm planning one myself, so here's the route I noted down:

Grab the scaffold — ZhijiangTang/dsh-plugin-template; scaffold.sh generates the skeleton in one command.
Read the minimal example — superfly/sprites-deepseek-plugin (a 169-line README that explains exactly how cordis.patch.yml and index.js combine an MCP client with a skill).
Read all 14 tiny zero-config plugins closely — you can finish one in an afternoon, which beats reading docs.

A standard bundle looks like this:

my-dsh-plugin/
├── cordis.patch.yml   # declares which dsh packages to mount + config
├── index.js           # entry: resolves assets via import.meta.url, mounts dsh services
├── package.json
└── skills/            # optional: bundled skill resources

A few conventions the community agrees on: zero config, small single-package surface, normalized failure values (a failing tool returns a human-readable error instead of throwing), and every package self-checks. Tag your repo #dsh and the community directory picks it up automatically.

Before you touch the source, etch these in

If you plan to modify DSH itself (as I do, since I want to fold it into the agent project I'm building), here are the conventions you'll hit constantly. The full list lives in the repo's AGENTS.md:

Every npm package is named @deepseek-ai/dsh-<name>; ESM everywhere ("type": "module").
Registrations are effects — every contribution goes through ctx.effect() / ctx.on().
Waterfall listeners MUST call next() — skip it and you short-circuit the whole chain. Reading the docs didn't make this click; crashing did.
Misconfiguration fails loud — if it can be self-contained, fail at load time, never silently skip.
Exactly one trailing newline at end of file; git diff --cached --check is the pre-commit gate.

Closing thoughts

What made DSH click for me wasn't that it has the most features. It's that it treats composability and traceability as first-class citizens rather than retrofitted patches.

Whether a system can grow depends on how clean its seams are. DSH's Service Definition / Provider / Consumer trio leaves a whole rack of standard slots for an agent — swapping model, sandbox, or storage is a one-Provider change. Add the "model-visible means logged" seatbelt on top, and together they're what move it from "yet another framework" to "something I'd bet my project's foundation on."

Next step: I want to wire that local TencentDB Agent Memory into DSH as a callable tool and run a real end-to-end scenario. I'll write it up once it actually works.

Entry points if you want to keep digging:

Official repo: https://github.com/deepseek-ai/deepseek-harness
Website: https://deepseek.com/harness/en/
Developer docs: https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart
Plugin marketplace: https://dshhub.org/ (9,400+ plugins, continuously scanned)
Cordis kernel: https://github.com/cordiverse/cordis

原文发表于沐沐ai专题

关注「沐沐ai专题」公众号，获取更多 AI 实战干货

Hands-on with Tencent Cloud Agent Memory: Giving AI a Real Long-Term Memory

liuyuyan6100 — Sun, 23 Aug 2026 11:30:42 +0000

I've been following an open-source project lately: Tencent Cloud's TencentDB Agent Memory (repo TencentCloud/tencentdb-agent-memory). The problem it tackles is simple but, until now, nobody had turned it into an engineering-grade system — how to stop an AI Agent from starting from scratch every single time.

This article is my learning notes written while reading the source code — not a sponsored post. I'll walk through its positioning, architecture, how memory "grows" layer by layer, how it retrieves and governs memory, and how to run it locally. At the end, I'll share why, as someone who works on both embedded systems and Agents, this project caught my attention.

1. What problem does it actually solve?

Anyone using Agents to write code or do ops has hit this: for the same project, you have to re-explain the context every time the conversation resets; the same document gets re-read by every Agent; a pitfall one workflow already hit gets hit all over again by the next Agent.

Re-explaining context, re-reading docs, re-discovering workflows — these three kinds of "repetition" are exactly what Agent Memory wants to eliminate.

Its own positioning, verbatim: team-level memory hub for AI Agents — turning conversations, documents, and code into four reusable memory assets (Chat Memory / Skill / LLM-Wiki / Code-Graph), then doing governance, sharing, and equipping between Agents and frameworks.

One distinction the project keeps stressing: it is not a chat-log warehouse. RAG only answers "can we find it"; Team Memory also has to answer "who can use it, which version is valid, which Agent should get it." The former is retrieval; the latter is governance.

Its slogan is blunt: Agents remember. Humans innovate.

2. How the four modules break down

The repo splits into four pieces with clear responsibilities:

Module	What it does	A detail I noted
MemoryCore	Memory & metadata core	Stores L0–L3 memory and asset metadata; exposed via HTTP Gateway (default `:8420`); SQLite + local files, BM25 recall by default
MemoryKnowledge	Knowledge parsing / indexing / retrieval	Stores only metadata, not the knowledge content itself; Wiki parsing, CodeGraph building, and index retrieval all happen here
MemoryPanel	Team memory panel (frontend)	Human-controllable console: Team Up / Asset Library / Agent Loadout / Knowledge Workshop / Access Control
MemoryProxy	Proxy layer	Zero-code integration via a stable protocol; Agents discover capabilities via `/v3/tools/list` and read pages/source/impact paths via `/v3/tools/call`

An easy-to-confuse point: MemoryCore does not store knowledge content. For example, when you import a product doc, MemoryCore only registers "which knowledge source, what type, status, relationships, service address" — the actual parsing and retrieval are delegated to MemoryKnowledge. This "metadata/content separation" makes permissions and migration much easier later.

3. How memory "grows": L0–L3

This is the part I most wanted to understand. It layers memory into four levels: conversations first land in L0, then an async pipeline refines them into higher-level assets:

L0 Conversation: Raw conversations with full context, timestamps, and source. Used to verify original statements.
L1 Atom: Facts, preferences, constraints, and events extracted from conversations. Precise recall of actionable info.
L2 Scenario: Knowledge blocks organized around a project/scenario. Quickly restore the working environment.
L3 Core / Persona: Long-term profile, stable patterns, high-level cognition. Lets an Agent enter the user/team context from the start.

Refinement is asynchronous — not real-time distillation every turn, but a pipeline that slowly aggregates L0 upward in the background. Documents and code take a different path: documents → Wiki pages (with a link graph you can drill into); code → CodeGraph (indexing symbols, files, call relationships, impact paths).

The closed loop is the essence of this design. There's a line from the project I copied into my notes: "A loop without memory just repeats faster; a loop that inherits memory can beat the last iteration every time." Valuable interactions are stored as Chat Memory → validated workflows are distilled into Skills → doc/code changes trigger Wiki ingest and CodeGraph sync.

4. Retrieval & governance: doing one more step beyond "can be found"

On retrieval it's not picky: normally bootstrap quickly with L2/L3, fall back to L1/L0 when you need specific facts. Underneath is BM25 + vector retrieval + RRF (Reciprocal Rank Fusion). Results are also capped by three limits — item count, character budget, and timeout — to prevent the context from being stuffed in one shot. This detail is pragmatic; RAG usually fails by cramming too much into the prompt at once.

Governance is where it pulls ahead of a plain vector DB:

Visibility semantics: private (owner only), team (team-readable), restricted (precise ACL by User/Role/Agent), agent (targeted equipping within the team).
Fixed Binding + ACL: first narrow asset permissions by Team/User/Agent/visibility, then retrieve by query. Which assets a given Agent can actually use is decided by this mechanism.
Generation provenance: the Prompt ID, version, source, and content SHA-256 actually used by L1/L2/L3 are all recorded, and you can pinpoint the generation log by Memory ID. But it doesn't store a snapshot of the Prompt body — guaranteeing traceability while avoiding hoarding the policy itself as data.

5. Cold start & team playbook

"Cold-start friendly" isn't a slogan. It can import an existing codebase (CodeGraph auto-indexes), documents (Wiki auto-generates), and historical sessions (auto-extracts Skills and Chat Memory) — the project calls this "loading the save file." A newly onboarded Agent team doesn't start from blank; it inherits existing experience.

The team-playbook example is also down-to-earth: a small team called "Tiny but Serious Inc." with members You / Scout / Builder / Reviewer, plus Agent Memory. Different roles equip different assets — Scout carries Chat Memory from user interviews and the market Wiki; Builder carries the product Wiki and CodeGraph. Same memory substrate, sliced into different views by role.

6. How to run it (local hands-on)

I followed along on the feat/server_team branch; spinning up MemoryCore locally is lightweight:

# MemoryCore is open-sourced as a Standalone Runtime
cd MemoryCore
npm install
npm run build

export TDAI_LLM_API_KEY="your-api-key"
export TDAI_LLM_BASE_URL="https://api.openai.com/v1"
export TDAI_LLM_MODEL="gpt-4o-mini"
node --import tsx src/gateway/server.ts

The Gateway listens on 127.0.0.1:8420 by default, using SQLite, local files, and in-process state. Other than the LLM API, there are no required external services, and it disables remote Embedding by default, using BM25 — very friendly for a local single machine. Data is written to ~/.memory-tencentdb/memory-tdai by default.

To launch the full stack in one go (memory-core + memory-hub + proxy), use the deploy script in the repo:

cd deploy/global-images
cp .env.example .env      # fill in two sets of LLM params (memory group + proxy group)
./start-all.sh            # prints a one-liner you can paste into Claude/CodeBuddy

The panel is at http://localhost:8125.

The Agent Adapter only needs to do three things, and the docs are refreshingly restrained: write L0 when the session ends or after each turn; recall L1/L2/L3 before constructing the Prompt; inject the recalled results into the Agent as bounded, identifiable context. For OpenClaw there's a ready-made openclaw-plugin/, for Hermes a hermes-plugin/, and for custom Runtimes the TS/Python SDK under sdk/memory-core/. The adapted Agent list includes DeepSeek Harness, Claude Code, Codex, CodeBuddy, WorkBuddy, Hermes, OpenClaw, with a Generic integration guide for anything not listed.

7. A few pitfalls and judgments I noted

A few points I hit (or predicted) while reading:

Wiki / CodeGraph are built asynchronously — after import you must wait for them to be ready; they're not queryable immediately. Any automation pipeline must budget for this latency.
CodeGraph currently prioritizes public HTTPS repos; private / SSH support is still maturing. On-prem codebases will have to wait.
v2 → v3 data migration must run a script first, and the docs explicitly say "back up the entire data directory before migrating." The data format goes from v2 to v3; before launching the new Gateway, probe with python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py <data-dir> --dry-run.
On security: listening on a non-loopback address requires TDAI_GATEWAY_API_KEY; CORS is off by default — don't use *; all Secrets go through environment variables. These are the baseline.
There's a benchmark figure that speaks to the value: on PersonaMem, a relative improvement of +59% (48% → 76%) — long-term persona memory makes cross-session understanding of Agents markedly better.

Why am I watching this project? Half my energy goes into embedded systems like ESP32, the other half into Agents. On the embedded side I'm researching ESP-Claw — a framework that burns an Agent Runtime into silicon so devices can decide locally. Cloud Agents and edge Agents look like two ends, but the memory substrate can be the same: during development, use an Agent to write firmware and store the pitfalls you hit as Skills; once the on-device Agent connects to sensors via MCP, it can also return to the central memory for context. TencentDB Agent Memory's idea of "memory/execution separation, governance across frameworks" is exactly the missing piece in that picture.

Conclusion

In the Agent industry, the first two years were about "who has the stronger model, who prompts better." Now it's slowly shifting to "who remembers" — not remembered in the chat box, but remembered as governable, shareable, cross-framework-reusable assets.

Tencent Cloud's open-source project has engineered this: four layers of memory, four kinds of assets, a set of governance semantics, and a proxy layer with a stable protocol. Agents remember. Humans innovate. — now I have a bit of a feel for that line.

If you're also working on Agent memory, or have already integrated this system, drop a comment on the blog about your real-world experience — what's good, what's still awkward — that's worth more than the docs.

原文发表于沐沐ai专题

关注「沐沐ai专题」公众号，获取更多 AI 实战干货