{"_id":"@tencentdb-agent-memory/memory-tencentdb-v2","name":"@tencentdb-agent-memory/memory-tencentdb-v2","dist-tags":{"beta":"1.0.0-beta.1","latest":"1.0.0-beta.1"},"versions":{"1.0.0-beta.1":{"name":"@tencentdb-agent-memory/memory-tencentdb-v2","version":"1.0.0-beta.1","description":"OpenClaw memory plugin — client mode for TencentDB Agent Memory Gateway","type":"module","main":"dist/index.js","types":"dist/index.d.ts","openclaw":{"extensions":["./dist/index.js"]},"scripts":{"clean":"rm -rf dist *.tgz","build":"tsc","prepack":"npm run clean && npm install --no-save --no-audit --no-fund && npm run build"},"dependencies":{"@tencentdb-agent-memory/memory-sdk-ts-v2":"1.0.0-beta.2"},"devDependencies":{"typescript":"^5.5.0","@types/node":"^22.0.0"},"engines":{"node":">=22.0.0"},"gitHead":"ce93615956c0b5d52d8520a39c64f6aaebdefeeb","_id":"@tencentdb-agent-memory/memory-tencentdb-v2@1.0.0-beta.1","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-1YsmNA1iDpkBBZwqSj1u2t5QRUh3zi2rTXB4j0oa9DldW+YdwTFLvbMLv7A+I8sf/tCLhw6y4pFkCxRf8LTHhQ==","shasum":"cfa27d3f7eeaedea47c907ddc8519041e992a24e","tarball":"https://registry.npmjs.org/@tencentdb-agent-memory/memory-tencentdb-v2/-/memory-tencentdb-v2-1.0.0-beta.1.tgz","fileCount":27,"unpackedSize":83032,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH4T+H3P7EfVT4DXuFcAxVMhSF8zfNlM2//pxaNmoFqmAiAfj70r7NGNBca+8m+X6zJTgTHRPNKuywxvavmf5rkZxg=="}]},"_npmUser":{"name":"yoimiyaxu","email":"ruidaxu@tencent.com"},"directories":{},"maintainers":[{"name":"peng-zou","email":"lynzou@tencent.com"},{"name":"cloudluo","email":"cloudluo@tencent.com"},{"name":"zarekzhang","email":"zarekzhang@tencent.com"},{"name":"yoimiyaxu","email":"ruidaxu@tencent.com"},{"name":"chrishuan","email":"chrishuan@tencent.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/memory-tencentdb-v2_1.0.0-beta.1_1786018575471_0.10178044239135864"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-06T12:16:15.290Z","1.0.0-beta.1":"2026-08-06T12:16:15.619Z","modified":"2026-08-06T12:16:15.928Z"},"maintainers":[{"name":"peng-zou","email":"lynzou@tencent.com"},{"name":"cloudluo","email":"cloudluo@tencent.com"},{"name":"zarekzhang","email":"zarekzhang@tencent.com"},{"name":"yoimiyaxu","email":"ruidaxu@tencent.com"},{"name":"chrishuan","email":"chrishuan@tencent.com"}],"description":"OpenClaw memory plugin — client mode for TencentDB Agent Memory Gateway","readme":"# OpenClaw Adapter for TencentDB Agent Memory (v3)\n\n[简体中文](./README_CN.md) · English\n\nThis directory is the **OpenClaw client adapter** for Memory Gateway **`/v3/*`**. It does not run extraction, indexing, scene generation, or persona generation. It connects to an already-running Memory Gateway and uses the npm TypeScript SDK to capture conversations, recall memories, and expose memory tools to the Agent.\n\n| Item | Value |\n|------|--------|\n| Plugin ID | `memory-tencentdb-client` (same historical ID; implementation is v3) |\n| SDK | [`@tencentdb-agent-memory/memory-sdk-ts-v2@1.0.0-beta.2`](https://www.npmjs.com/package/@tencentdb-agent-memory/memory-sdk-ts-v2/v/1.0.0-beta.2) (npm; root = v3) |\n| Data plane | `MemoryClient` → `/v3/*` + isolation (`teamId` / `agentId` / `userId`) |\n| COS read | Tool `tdai_read_cos` via `createMemoryFileReader` (`POST /v2/cos/secret` + STS) |\n| Not included | Offload / Context Engine |\n\nFor local standalone Gateway, use `http://127.0.0.1:8420` with `apiKey = \"local\"`, `instanceId = \"default\"`, and isolation triple `\"default\"` (aligned with `DEFAULT_ISOLATION_ID`). If the Gateway enables `TDAI_GATEWAY_API_KEY`, set `server.apiKey` to the same value.\n\nMore design detail: `../docs/design/2026-07-20-v3-plugin-install-dual-mode-design.md`, `docs/architecture.md`.\n\n## Architecture\n\n```text\nOpenClaw runtime\n └─ memory-tencentdb-client plugin\n ├─ hooks/capture.ts agent_end → addConversation (L0, /v3)\n ├─ hooks/recall.ts before_prompt_build → search + prompt injection\n ├─ tools/memory-search.ts tdai_memory_search → searchAtomic (L1)\n ├─ tools/conversation-search.ts tdai_conversation_search → searchConversation (L0)\n └─ tools/read-cos.ts tdai_read_cos → MemoryFileReader (COS STS)\n │\n ▼\n @tencentdb-agent-memory/memory-sdk-ts-v2\n │ MemoryClient → HTTP /v3/*\n │ createMemoryFileReader → /v2/cos/secret + STS GET\n ▼\n TencentDB Agent Memory Gateway (:8420 standalone, or remote service)\n```\n\n## Tools\n\n| Tool | Purpose |\n|------|---------|\n| `tdai_memory_search` | Search L1 structured memories |\n| `tdai_conversation_search` | Search L0 conversation history |\n| `tdai_read_cos` | Read memory files by relative path (`scene_blocks/…`, `persona.md`, …) |\n\n## Dual mode (Gateway deployment)\n\n| Mode | Meaning |\n|------|---------|\n| `local` | Gateway at `127.0.0.1:8420`, placeholder auth + isolation |\n| `server` | Remote Gateway; real API Key + instance + isolation required |\n\nBoth modes use the **same npm SDK** (`memory-sdk-ts-v2`). “Online/offline” here means Gateway deployment (local vs server), not how the SDK package is obtained.\n\n## Quick Start\n\nRecommended: from `MemoryCore/`, run the v3 installer (wrapper around `npm install` for the SDK + plugin build + `openclaw plugins install -l` + config write):\n\n```bash\n# Local Gateway (defaults)\nbash scripts/install-openclaw-plugin.sh\n\n# Remote Gateway (strict)\nMEMORY_INSTALL_MODE=server \\\n TDAI_MEMORY_ENDPOINT=\"https://memory.example.com\" \\\n TDAI_MEMORY_API_KEY=\"\" \\\n TDAI_MEMORY_INSTANCE_ID=\"\" \\\n TDAI_MEMORY_TEAM_ID=\"team-...\" \\\n TDAI_MEMORY_AGENT_ID=\"agent-...\" \\\n TDAI_MEMORY_USER_ID=\"user-...\" \\\n bash scripts/install-openclaw-plugin.sh\n```\n\nThe script installs/builds this plugin (`npm install` pulls the SDK from the registry), runs `openclaw plugins install -l`, and updates `~/.openclaw/openclaw.json`: `plugins.slots.memory = \"memory-tencentdb-client\"`, enables the entry, and writes `server` (including isolation), `recall`, and `capture`. On **OpenClaw >= 2026.4.24** it also writes `hooks.allowPromptInjection` / `hooks.allowConversationAccess`; on older versions those fields are **omitted**.\n\nUseful env overrides: `OPENCLAW_CONFIG_FILE`, `TDAI_MEMORY_ENDPOINT`, `TDAI_MEMORY_API_KEY`, `TDAI_MEMORY_INSTANCE_ID`, `TDAI_MEMORY_TEAM_ID`, `TDAI_MEMORY_AGENT_ID`, `TDAI_MEMORY_USER_ID`, `WRITE_OPENCLAW_CONFIG=0`.\n\nOpenClaw does **not** invoke this script by itself. You can skip it and install manually (below).\n\n### 1. Install OpenClaw CLI\n\n```bash\ncurl -fsSL https://get.openclaw.dev | bash\nopenclaw --version\n```\n\n### 2. Install plugin dependencies and build\n\n```bash\ncd MemoryCore/openclaw-plugin\nnpm install\nnpm run build\n```\n\n`package.json` depends on npm package [`@tencentdb-agent-memory/memory-sdk-ts-v2@1.0.0-beta.2`](https://www.npmjs.com/package/@tencentdb-agent-memory/memory-sdk-ts-v2/v/1.0.0-beta.2) (root entry = v3).\n\n### 3. Link into OpenClaw\n\n```bash\nopenclaw plugins install -l .\n```\n\n### 4. Configure the plugin\n\nThe installer writes config by default. Edit manually only when using `WRITE_OPENCLAW_CONFIG=0` or a fully manual install.\n\n> **Important — `hooks.*` is version-gated.** \n> `hooks.allowPromptInjection` / `hooks.allowConversationAccess` are accepted from **OpenClaw `2026.4.24`**. Earlier versions use a strict schema and will **refuse to start** if these fields are present. Check with `openclaw --version`.\n\n**Example A — OpenClaw `>= 2026.4.24` (recommended):**\n\n```jsonc\n{\n \"plugins\": {\n \"slots\": {\n \"memory\": \"memory-tencentdb-client\"\n },\n \"entries\": {\n \"memory-tencentdb-client\": {\n \"enabled\": true,\n \"hooks\": {\n \"allowPromptInjection\": true,\n \"allowConversationAccess\": true\n },\n \"config\": {\n \"server\": {\n \"url\": \"http://127.0.0.1:8420\",\n \"apiKey\": \"local\",\n \"instanceId\": \"default\",\n \"teamId\": \"default\",\n \"agentId\": \"default\",\n \"userId\": \"default\"\n },\n \"recall\": {\n \"maxResults\": 5,\n \"includePersona\": true,\n \"includeSceneNav\": true\n },\n \"capture\": {\n \"enabled\": true\n }\n }\n }\n }\n }\n}\n```\n\n**Example B — OpenClaw `< 2026.4.24`:** omit the `hooks` block entirely; keep the same `config` (including isolation).\n\n`server.instanceId` is sent as `x-tdai-service-id`. Isolation is passed to the v3 SDK at construct time. On remote (`server` install mode), do not use placeholder `local` / `default` unless you set the installer escape hatches.\n\n- `hooks.allowPromptInjection` — allows `before_prompt_build` to inject recalled context. \n- `hooks.allowConversationAccess` — required `true` for non-bundled plugins on 2026.4.24+, otherwise L0 capture is silently blocked.\n\n### 5. Restart OpenClaw Gateway\n\n```bash\nopenclaw gateway restart\n```\n\n## Adapter Responsibilities\n\n| Area | Implementation | Description |\n|------|----------------|-------------|\n| Capture | `src/hooks/capture.ts` | Writes completed turns to L0 via v3 `addConversation()` |\n| Recall | `src/hooks/recall.ts` | Searches before prompt build and injects concise context |\n| L1 tool | `src/tools/memory-search.ts` | Agent search of structured memories |\n| L0 tool | `src/tools/conversation-search.ts` | Agent search of raw conversation history |\n| File read | `src/tools/read-cos.ts` | Agent read of pipeline artifacts via COS STS |\n\n## Configuration\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `server.url` | `http://127.0.0.1:8420` | Memory Gateway URL |\n| `server.apiKey` | `local` | Bearer token; use `local` for default standalone |\n| `server.instanceId` | `default` | Sent as `x-tdai-service-id` |\n| `server.teamId` | `default` | v3 isolation `team_id` |\n| `server.agentId` | `default` | v3 isolation `agent_id` |\n| `server.userId` | `default` | v3 isolation `user_id` |\n| `server.rejectUnauthorized` | `true` | TLS certificate verification |\n| `recall.maxResults` | `5` | Max L1 memories injected per turn |\n| `recall.includePersona` | `true` | Include L3 core/profile |\n| `recall.includeSceneNav` | `true` | Include L2 scene navigation |\n| `capture.enabled` | `true` | Auto-capture completed turns |\n| `hooks.allowPromptInjection` | `true` | Only write on OpenClaw `>= 2026.4.24` |\n| `hooks.allowConversationAccess` | `true` | Only write on OpenClaw `>= 2026.4.24`; required for L0 on non-bundled plugins |\n\n## Files\n\n```text\nopenclaw-plugin/\n├── openclaw.plugin.json # plugin manifest (id = memory-tencentdb-client)\n├── package.json # npm: @tencentdb-agent-memory/memory-sdk-ts-v2\n├── index.ts # OpenClaw entrypoint (v3 client + COS reader)\n├── src/hooks/capture.ts # L0 capture\n├── src/hooks/recall.ts # recall + prompt injection\n├── src/tools/ # Agent-callable tools (incl. read-cos)\n├── src/format.ts # prompt formatting\n└── docs/architecture.md # deeper architecture notes\n```\n\n## Using This as an Adapter Template\n\nWhen adapting another Agent framework, reuse the same pattern:\n\n1. After a user/assistant turn, call v3 `addConversation()` (with isolation).\n2. Before the next prompt, call `searchAtomic()`, `readCore()`, and optionally `listScenarios()`.\n3. Inject only concise, labeled memory context.\n4. Expose tools for L1 search, L0 conversation search, and COS file read (`MemoryFileReader`).\n5. Keep the adapter stateless; the Memory Gateway owns storage and async L1/L2/L3 processing.\n\n## Notes\n\n- Client adapter only: do not start a Memory Gateway subprocess or implement extraction locally.\n- Standalone without COS/STS: `tdai_read_cos` returns a readable error; capture/recall must not depend on it.\n- For Gateway startup and broader SDK examples, see the repository root README.\n","readmeFilename":"README.md","_rev":"1-3c46cd57a8fec4f1c7f4fc4709465077"}