From Creating a New Project to Managing Memory with the SDK
This page prepares the project in the actual integration order; the next page provides runnable SDK examples. Applies to Agentbase 2.10.0; Node.js examples use agentbase-node-sdk@2.9.0.
First Complete a Demo Project
Log in to the Console and enter the organization; if there is no organization, create one first.
Click Create Project, fill in a name, for example “Coffee Assistant”, and submit according to the region and database resource pool tags provided on the page. Note down the project ID, and confirm on the Memory page that enabling is supported; Shared V2 is determined by the resource pool used by the project, not an independent option in the creation form.
Enter the project's Model Management (LLM Gateway) and configure the Embedding and Chat providers and models. If rerank or sparse is not used yet, turn off the corresponding optional items in the enablement wizard.
Return to the Memory enablement wizard, choose the models, actual vector dimensions, and quota, then submit and wait for the project to become active and the data ready.
Open memory → Add memory, fill in the user ID with
demo-user, select user as the scope, under processing mode choose Write directly, set the memory type to preference and the record kind to fact (fact), and save “The user likes lattes.”.Filter the list by that user ID and verify the record content and ID. The SDK subsequently uses the same project and target user.
See Getting started with memory from project creation for detailed Console operations. Project enablement no longer requires creating a Memory Resource or binding resources.
Create an API Key for the Server Side
In the project's Overview → Integrations → API keys, choose to create an API Key:
| Planned operations | Required scope |
|---|---|
| Read-back, listing, search, unified recall, reading profile and distillation status | memories.read |
| Write, update, query async write tasks, extract profile and distill | memories.write |
| Forget this demo's memories | memories.delete |
| Export | memories.export |
Copy the region endpoint, project ID, and key. The SDK's endpoint includes /v1, e.g. https://<agentbase-host>/v1; do not copy the Console page URL. The key comes from the target project's API keys; the Console login account and the business userId are different concepts; this demo uses the business user identifier demo-user.
Store the key only in backend environment variables or a secret management facility. Browsers use the user Session; never put the project API Key in frontend code. Cross-user reads or writes are authorized by the business backend.
Install and Run
Prepare Node.js 20 or higher, and in a new local demo directory run:
mkdir memory-demo
cd memory-demo
npm init -y
npm install --save-exact agentbase-node-sdk@2.9.0Then configure the environment variables:
export APPBASE_ENDPOINT="https://<agentbase-host>/v1"
export APPBASE_PROJECT_ID="<project-id>"
export APPBASE_API_KEY="<project-api-key>"
export APPBASE_USER_ID="demo-user"
export MEMORY_OPERATION_ID="$(node -p 'require("node:crypto").randomUUID()')"Save the complete SDK example as memory-demo.mjs and run:
node memory-demo.mjsThe example sequentially creates a new memory tagged with this run's operation marker, reads it back, lists by user, performs semantic search, performs unified recall, updates it with a version, and finally proactively deletes the memory it just created. Before running, grant the demo Key the three permissions memories.read, memories.write, and memories.delete. The example does not delete the memory created manually in the Console earlier; proactive deletion is irreversible.
MEMORY_OPERATION_ID is the idempotency identifier of a single logical creation. Keep the original value when retrying the same creation after a timeout; use a new value when starting a different write. The complete script includes the final deletion; after deletion, do not replay the whole script as-is as if it were the same single creation.
The example puts this run's operation marker into the demo content to distinguish the new demo round from the previously deleted content. Real applications should preserve the original meaning of the business content; when the same forgotten content genuinely needs to be re-learned, explicitly use reRemember=true and a new idempotency key to create new evidence. Merely changing the idempotency key cannot bypass content protection.
How to Use in an Application
| User behavior | SDK operation | Read results |
|---|---|---|
| The user explicitly tells the app a fact | create, infer=false, specify the decay period via memoryType (working / short_term / long_term) and the visibility scope scope (strict_private / private / user / group / project) | status=completed then read memory.memoryId. |
| After a conversation ends, extract information worth keeping long-term (or multimodal image/PDF extraction) | create, infer=true, sessionId (automatically associates the most recent 12 turns of context), handlingPolicy (standard / no_embedding / no_model), media: {bucketId, fileId}, or relearn forgotten memory reRemember: true | usually returns jobId, poll getJob; check result.status and actions (ADD / UPDATE / DELETE / NONE). |
| Open that user's memory management page | list, get | memories / memory; pass the list pagination parameter through as-is in nextCursor. |
| Send a new question, using five-way hybrid retrieval, model-generated sparse vectors, or progressive retrieval | search (mode: hybrid|vector|keyword|graph|profile, retrieval.sparse: true|false|"auto", retrieval.strategy: "progressive", deadlineMs: 450) | For regular hits read items[].memory; for progressive retrieval read progressive.items (L3 domain overview → L2 contextual topic → L1 atomic fact → L0 raw evidence) and use expansionToken to expand the next layer; check degraded. |
| Assemble user profile, experience, skills, and memory context | recallKnowledge (joint retrieval within a unified token budget: memory + profile + experience + skill) | context, items, usedTokens, injectionId, degraded; the app then feeds the needed context into its own model calls, and can use injectionId to call createKnowledgeFeedback / createKnowledgeObservation for attribution. |
| Distill experience/skills from multi-turn conversations and tool traces, and perform context dreaming (Dreaming) | submitDistillation (mode: "async" | "wait", messages, toolEvents), createContextRun, confirmContext / rebuildContext / rollbackContext | Poll getDistillation Check candidate outputs and promote them to production via the self-evolution approval form (/v1/memory/memories/knowledge/reviews/{reviewId}/approve|reject). |
| The user corrected a fact | get then update | Pass the current memory.version and save the newly returned version. |
| The user requests deletion of a piece of information | delete / deleteMany | Returns status=forgotten; proactively delete the record and retrieval data; source evidence and audit may still be retained. |
Search and retrieval are not the same as asking a chat model a question, and they do not automatically generate a final answer for the app. After a write completes, vector projections and the like may still be prepared in the background; when semantic results are empty, first check the user, scope, and index status instead of immediately writing again.
Continue integration
Memory operations and asynchronous extraction examples: complete Node.js workflow plus existing operation cards in multiple languages.
REST API reference: parameters, real response structures, errors, and edge cases.
Server-side Node.js initialization, Web user Session, SDK installation.
Newly added fields such as pipelineId and media input follow the server-side REST contract. The create/search of the released 2.9.0 SDK does not include media, and create, createImport, createProfileExtraction, and submitDistillation do not include pipelineId; stuffing extra properties into the object will not make the SDK send them. For these capabilities, use REST first or an SDK verified to have the corresponding signatures.
Management boundaries and pipeline/configuration namespaces
Enabling, permanently deleting project Memory, the six configuration namespaces, and the four types of memory pipelines are managed in the Console or a controlled admin endpoint; these operations do not use the ordinary project API Key demonstrated on this page. The management-plane PATCH /v1/projects/{projectId}/memory uses enabled=false to disable project Memory while retaining the data; the Services toggle in project Settings only controls client access and cannot replace disabling Memory as a whole. DELETE /v1/projects/{projectId}/memory is permanent deletion, not unbinding. The legacy Resource/claim interfaces are not used as an initialization step for new projects.
Six configuration namespaces (
GET/PUT /v1/projects/{projectId}/memory/config/{namespace}): coveringruntime(five-way fusion and progressive retrieval),prompt(extraction/dreaming/distillation prompts),policy(access isolation and filtering whitelist),retention(working/short-term memory retention and forgetting cycles),provider(LLM Gateway model bindings andsparseMode: "auto"), andevolution(self-evolution distillation and manual approval gates). Every update must carry theexpectedConfigVersionandIf-Matchheaders to prevent overwriting concurrent modifications.Four types of memory pipelines (
/v1/memory/pipelines): coveringadd_memory,profile,distillation, andforgetting(Ebbinghaus forgetting pipeline). Theforgettingpipeline supports a single-user Ebbinghaus forgetting curve preview viaPOST /v1/memory/pipelines/{id}/validate(passingdryRun: trueandsampleUserId); after confirming it is correct,publishand set it as the default pipeline viaPUT /v1/memory/pipelines/default.Profile and self-evolution approvals: profile replacement (
mode: "replace") requires a newmessages;sourceMemoryIdsserves only as supplementary evidence; deleting the profile preserves the original memory. Candidate experiences and skills produced by distillation are approved via/v1/memory/memories/knowledge/reviews/{reviewId}(approve/reject) or compared and rolled back by revision (/revisions,/diff,/rollback); manual approval requires a real admin user, and an ordinary project API Key cannot act as the approver.
Applicable Versions
The server-side workflow applies to Agentbase 2.10.0; the Node.js examples use agentbase-node-sdk@2.9.0. For full installation instructions see SDK integration; the newly added HTTP fields will not automatically appear in that SDK version's requests.