Debugging MemoryNode

You do not need a special dashboard to understand what the API did. Use response bodies, x-request-id, and optional explain on search.

Always log `x-request-id`

Every success and error includes x-request-id (and request_id in JSON errors). Log it in your app; send it with support or POST /v1/feedback.

After a write (`POST /v1/memories`)

Signal	Meaning
`deduped: true`	Near-duplicate text; existing `memory_id` reused
`superseded_memory_id`	You passed `replaces_memory_id`; old row superseded
`intelligence.conflict_state`	Contradiction handling (`candidate`, `resolved`, `superseded`, …)
`extraction.status`	`skipped` / `degraded` / `run` — not a hard failure

SDK helper

import { MemoryNode, formatMemoryWriteDebug } from "@memorynodeai/sdk";

const res = await memory.remember("...");
console.log(formatMemoryWriteDebug(res).join("\n"));
// or: memory.formatWriteDebug(res)

After a search (`POST /v1/search`)

Pass explain: true to attach ranking_reason string codes on each hit (REST only).

curl -sS -X POST "https://api.memorynode.ai/v1/search" \
  -H "Authorization: Bearer $MEMORYNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"preferences","top_k":5,"explain":true}'

SDK

const hits = await memory.recall("preferences", { explain: true });
console.log(memory.formatSearchDebug(hits).join("\n"));

Codes map to plain language via RANKING_REASON_LABELS in @memorynodeai/sdk.

Empty search results

Confirm the same owner (user_id / owner_id) and namespace as ingest.
Wait a few seconds after first write (embedding/index path).
Try search_mode: "keyword" once to verify text is stored.
Check plan usage: GET /v1/usage/today.

Replay a prior search

GET /v1/search/history and POST /v1/search/replay (SDK: listSearchHistory, replaySearch) — compare results without re-typing the query.

MCP / agents

Hosted MCP tools return the same memory IDs; enable logging in your MCP client and correlate with x-request-id from REST calls in the same session.