()
+ for (const entry of directoryEntries) {
+ for (const category of entry.categories) {
+ counts.set(category, (counts.get(category) ?? 0) + 1)
+ }
+ }
+ return [...counts.entries()]
+ .sort((a, b) => b[1] - a[1])
+ .slice(0, 10)
+ .map(([category]) => category)
+ }, [directoryEntries])
+
+ const marketplaceEntries = useMemo(
+ () =>
+ marketplaceCategory === "all"
+ ? directoryEntries
+ : directoryEntries.filter((entry) =>
+ entry.categories.includes(marketplaceCategory),
+ ),
+ [directoryEntries, marketplaceCategory],
+ )
+
+ const needle = query.trim().toLowerCase()
+ const searching = needle.length > 0
+ const catalogMatches = searching
+ ? apps.filter(
+ (entry) =>
+ entry.name.toLowerCase().includes(needle) ||
+ entry.category.toLowerCase().includes(needle),
+ )
+ : []
+ const slackMatches = searching && "slack messaging".includes(needle)
+
if (!isCompanyBrain) {
return (
entry.slug))
- const canClassifyCustomRows = catalogLoaded && apps.length > 0
- const customRows = canClassifyCustomRows
- ? rows.filter(
- (row) =>
- row.userId !== null &&
- row.status === "active" &&
- typeof row.serverUrl === "string" &&
- row.serverUrl.length > 0 &&
- !catalogSlugs.has(row.serverSlug),
- )
- : []
+ const slackInstallHref = `${BACKEND}/brain/slack/oauth/install`
+
+ const disconnectSlack = async () => {
+ try {
+ const res = await fetch(`${BACKEND}/brain/slack/workspace`, {
+ method: "DELETE",
+ credentials: "include",
+ })
+ if (res.status === 403) {
+ toast.error("Only admins can disconnect Slack.")
+ return
+ }
+ if (!res.ok) {
+ toast.error("Couldn't disconnect Slack.")
+ return
+ }
+ } catch {
+ toast.error("Couldn't disconnect Slack.")
+ return
+ }
+ toast.success("Slack disconnected.")
+ await load().catch(() => undefined)
+ }
+
+ const slackCard = (
+ connect(entry, shared)}
+ onDisconnect={(shared) => disconnect(entry, shared)}
+ />
+ )
+
return (
-
- {loading ? (
- <>
-
-
-
-
- ) : (
- <>
-
{
- try {
- const res = await fetch(`${BACKEND}/brain/slack/workspace`, {
- method: "DELETE",
- credentials: "include",
- })
- if (res.status === 403) {
- toast.error("Only admins can disconnect Slack.")
- return
- }
- if (!res.ok) {
- toast.error("Couldn't disconnect Slack.")
- return
- }
- } catch {
- toast.error("Couldn't disconnect Slack.")
- return
- }
- toast.success("Slack disconnected.")
- await load().catch(() => undefined)
- }}
- />
- {apps.map((entry) => (
- connect(entry, shared)}
- onDisconnect={(shared) => disconnect(entry, shared)}
- />
- ))}
- {customRows.map((row) => (
- {}}
- onDisconnect={() =>
- disconnect(
- {
- slug: row.serverSlug,
- name: titleCase(row.serverSlug.replace(/-/g, " ")),
- category: "Custom OAuth MCP",
- authType: "oauth",
- },
- false,
- )
- }
- />
- ))}
- setCustomOpen(true)}
- className={cn(
- dmSans125ClassName(),
- "flex min-h-[104px] cursor-pointer items-center justify-center gap-2 rounded-xl border border-[#2A313C] border-dashed",
- "text-[13px] font-medium text-[#737B87] transition-colors hover:border-[#3A4150] hover:text-[#FAFAFA]",
- )}
- >
-
-
- )}
+
+ {loading ? (
+
+
+ ) : searching ? (
+
+ {slackMatches || catalogMatches.length > 0 ? (
+
+ {slackMatches ? slackCard : null}
+ {catalogMatches.map((entry) => (
+
{appCard(entry)}
+ ))}
+
+ ) : null}
+
0}
+ />
+
+ {hasInstalled ? (
+
+ Installed
+
+ {slackConnected ? (
+
}
+ >
+ {isAdmin ? (
+ <>
+
+ Reconnect
+
+
{
+ if (window.confirm("Disconnect Slack?")) {
+ void disconnectSlack()
+ }
+ }}
+ >
+ Disconnect
+
+
+ ) : (
+
+ Managed by workspace admins
+
+ )}
+
+ ) : null}
+ {installedApps.map((entry) => {
+ const userConnected = isConnected(entry.slug, false)
+ const orgConnected = isConnected(entry.slug, true)
+ return (
+
+ {isAdmin ? (
+ <>
+
+ userConnected
+ ? disconnect(entry, false)
+ : connect(entry, false)
+ }
+ >
+ {userConnected
+ ? "Disconnect my account"
+ : "Connect my account"}
+
+
+ orgConnected
+ ? disconnect(entry, true)
+ : connect(entry, true)
+ }
+ >
+ {orgConnected
+ ? "Disconnect workspace"
+ : "Connect for workspace"}
+
+
+ ) : userConnected ? (
+ disconnect(entry, false)}
+ >
+ Disconnect
+
+ ) : (
+
+ Managed by workspace admins
+
+ )}
+
+ )
+ })}
+ {customRows.map((row) => (
+
+
+ disconnect(
+ {
+ slug: row.serverSlug,
+ name: customConnectionName(row.serverSlug),
+ category: "Custom MCP",
+ authType: "oauth",
+ },
+ false,
+ )
+ }
+ >
+ Disconnect
+
+
+ ))}
+
+ ) : null}
+
+ {!slackConnected ? (
+ {slackCard}
+ ) : null}
+ {recommendedApps.map((entry) => (
+
+ {appCard(entry)}
+
+ ))}
+ {recommendedDirectoryEntries.map((entry) => (
+
+
+ ))}
+
+
+
+
Marketplace
+ {marketplaceEntries.length > 0 ? (
+
+ {marketplaceEntries.length.toLocaleString()} servers
+
+ ) : null}
+
+ {marketplaceCategories.length > 0 ? (
+
+ {["all", ...marketplaceCategories].map((category) => (
+ setMarketplaceCategory(category)}
+ className={cn(
+ "h-7 shrink-0 cursor-pointer whitespace-nowrap rounded-full px-3 text-[12px] font-medium transition-colors",
+ marketplaceCategory === category
+ ? "bg-[#252B34] font-semibold text-[#FAFAFA]"
+ : "text-[#737373] hover:bg-[#14161A] hover:text-[#D4D4D8]",
+ )}
+ >
+ {category === "all" ? "All" : categoryLabel(category)}
+
+ ))}
+
+ ) : null}
+
+
+ onOpenChange={(open: boolean) =>
open ? setCustomOpen(true) : resetCustomForm()
}
>
@@ -755,11 +1099,14 @@ export default function CompanyBrainConnections() {
- Add custom connector
+ {directoryEntry
+ ? `Set up ${directoryEntry.name}`
+ : "Add custom connector"}
- Connect your Brain to any remote MCP server. Signs in with OAuth
- unless you add an API key below.
+ {directoryEntry?.availability === "tenant"
+ ? "Enter your workspace-specific MCP URL, then choose how this server authenticates."
+ : "Confirm the remote MCP URL, then choose how this server authenticates."}
-
setCustomAdvancedOpen((open) => !open)}
- className="mt-1 flex items-center gap-1.5 self-start text-[13px] font-medium text-[#FAFAFA]"
+
- setCustomAuthMethod(method)}
+ className={cn(
+ "h-8 rounded-full text-[12px] font-semibold transition-colors",
+ customAuthMethod === method
+ ? "bg-[#252B34] text-[#FAFAFA]"
+ : "text-[#737373] hover:text-[#D4D4D8]",
+ )}
+ >
+ {method === "oauth" ? "OAuth" : "API key"}
+
+ ))}
+
- {customAdvancedOpen && (
-
-
setCustomToken(event.target.value)}
- type="password"
- placeholder="API key (optional)"
- className={customInputClass}
+ {customAuthMethod === "api-key" && (
+
setCustomToken(event.target.value)}
+ type="password"
+ placeholder="API key"
+ required
+ className={customInputClass}
+ />
+ )}
+
+ {customAuthMethod === "api-key" && (
+
setCustomAdvancedOpen((open) => !open)}
+ className="mt-1 flex items-center gap-1.5 self-start text-[13px] font-medium text-[#FAFAFA]"
+ >
+
+ )}
+
+ {customAuthMethod === "api-key" && customAdvancedOpen && (
+
setCustomHeaderName(event.target.value)}
diff --git a/apps/web/components/settings/mcp-directory-browser.tsx b/apps/web/components/settings/mcp-directory-browser.tsx
new file mode 100644
index 00000000..4fe323ee
--- /dev/null
+++ b/apps/web/components/settings/mcp-directory-browser.tsx
@@ -0,0 +1,329 @@
+"use client"
+
+import { Loader2 } from "lucide-react"
+import { useEffect, useMemo, useState } from "react"
+import type { McpDirectoryEntry } from "@/lib/mcp-directory"
+import { brainConnectorIcon } from "../brain-connector-icons"
+import { ConnectorCard, ScopeChip } from "../directory/connector-card"
+import { PillButton } from "../integrations/install-steps"
+
+const BACKEND =
+ process.env.NEXT_PUBLIC_BACKEND_URL ?? "https://api.supermemory.ai"
+
+let directoryCache: McpDirectoryEntry[] | null = null
+
+function isDirectoryEntry(value: unknown): value is McpDirectoryEntry {
+ if (!value || typeof value !== "object") return false
+ const entry = value as Partial
+ return (
+ typeof entry.id === "string" &&
+ typeof entry.name === "string" &&
+ (entry.type === "remote" || entry.type === "local") &&
+ (entry.url === null || typeof entry.url === "string") &&
+ typeof entry.auth === "string" &&
+ (entry.note === null || typeof entry.note === "string") &&
+ Array.isArray(entry.categories) &&
+ entry.categories.every((category) => typeof category === "string") &&
+ typeof entry.popularity === "number" &&
+ (entry.iconDomain === null || typeof entry.iconDomain === "string") &&
+ ["custom", "unsupported"].includes(entry.setup ?? "") &&
+ (entry.oauthCapability === null ||
+ ["dcr", "preregistered"].includes(entry.oauthCapability ?? "")) &&
+ Array.isArray(entry.authMethods) &&
+ entry.authMethods.every((method) =>
+ ["oauth", "api-key"].includes(method),
+ ) &&
+ ["fixed", "tenant", "unavailable", "local"].includes(
+ entry.availability ?? "",
+ )
+ )
+}
+
+function parseDirectory(value: unknown) {
+ if (!value || typeof value !== "object") throw new Error("invalid catalog")
+ const entries = (value as { entries?: unknown }).entries
+ if (!Array.isArray(entries) || !entries.every(isDirectoryEntry)) {
+ throw new Error("invalid catalog")
+ }
+ return entries
+}
+
+async function loadDirectory(signal: AbortSignal) {
+ if (directoryCache) return directoryCache
+ const response = await fetch(`${BACKEND}/brain/mcp-connections/directory`, {
+ signal,
+ cache: "default",
+ credentials: "include",
+ })
+ if (!response.ok) throw new Error("catalog request failed")
+ directoryCache = parseDirectory(await response.json())
+ return directoryCache
+}
+
+export function useMcpDirectory() {
+ const [entries, setEntries] = useState(
+ () => directoryCache ?? [],
+ )
+ const [error, setError] = useState(false)
+
+ useEffect(() => {
+ const controller = new AbortController()
+ void loadDirectory(controller.signal)
+ .then((data) => {
+ setEntries(data)
+ setError(false)
+ })
+ .catch((error: unknown) => {
+ if (error instanceof DOMException && error.name === "AbortError") return
+ setError(true)
+ })
+ return () => controller.abort()
+ }, [])
+
+ return { entries, error }
+}
+
+export function categoryLabel(value: string) {
+ return value
+ .split("-")
+ .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+ .join(" ")
+}
+
+export function entrySlug(entry: McpDirectoryEntry) {
+ return entry.name
+ .trim()
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, "-")
+ .replace(/^-+|-+$/g, "")
+ .slice(0, 63)
+}
+
+// Mirrors the backend's URL normalization so connection rows match entries.
+export function normalizeServerUrl(value: string) {
+ try {
+ const url = new URL(value)
+ return `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, "")}`.toLowerCase()
+ } catch {
+ return value.toLowerCase()
+ }
+}
+
+// An entry we can actually take the user through connecting.
+export function isEntrySetUppable(entry: McpDirectoryEntry) {
+ return (
+ entry.setup !== "unsupported" &&
+ entry.authMethods.length > 0 &&
+ (entry.availability === "fixed" || entry.availability === "tenant")
+ )
+}
+
+// Entries worth listing at all — servers with no reachable URL are dropped.
+export function listableDirectoryEntries(entries: McpDirectoryEntry[]) {
+ return entries.filter((entry) => entry.availability !== "unavailable")
+}
+
+export function entryMatchesQuery(entry: McpDirectoryEntry, needle: string) {
+ return [entry.name, entry.url, entry.note, ...entry.categories]
+ .filter(Boolean)
+ .some((value) => value?.toLowerCase().includes(needle))
+}
+
+function DirectoryIcon({ entry }: { entry: McpDirectoryEntry }) {
+ const [failed, setFailed] = useState(false)
+ if (!entry.iconDomain || failed) {
+ return brainConnectorIcon(entrySlug(entry), entry.name, "size-4")
+ }
+ return (
+ onSetUp(entry)}>Set up
+ ) : null
+ }
+ />
+ )
+}
+
+function entrySubtitle(entry: McpDirectoryEntry) {
+ if (entry.categories.length > 0) {
+ return entry.categories.slice(0, 2).map(categoryLabel).join(" · ")
+ }
+ return entry.type === "local" ? "Desktop extension" : "MCP server"
+}
+
+// One directory listing: a dense single-line row. The default state carries no
+// status text — in a marketplace, "not connected" is implied. Only connection,
+// or the reason there's no button, earns words.
+export function DirectoryEntryRow({
+ entry,
+ connected,
+ onSetUp,
+}: {
+ entry: McpDirectoryEntry
+ connected: boolean
+ onSetUp: (entry: McpDirectoryEntry) => void
+}) {
+ const canSetUp = !connected && isEntrySetUppable(entry)
+ return (
+
+
+
+
+
+ {entry.name}
+
+
+ {entrySubtitle(entry)}
+
+
+ {connected ? (
+
+
+ ) : canSetUp ? (
+
onSetUp(entry)}
+ className="h-7 shrink-0 cursor-pointer rounded-full bg-[#1B2028] px-3 text-[12px] font-medium text-[#FAFAFA]/70 transition-colors group-hover:bg-[#252C37] group-hover:text-[#FAFAFA] hover:bg-[#2B3340]"
+ >
+ Set up
+
+ ) : (
+
+ {entry.availability === "local" ? "Desktop only" : "Coming soon"}
+
+ )}
+
+ isEntryConnected: (entry: McpDirectoryEntry) => boolean
+ onSetUp: (entry: McpDirectoryEntry) => void
+ // the caller rendered its own matches, so an empty grid isn't "no results"
+ suppressEmpty?: boolean
+}) {
+ const [visibleCount, setVisibleCount] = useState(GRID_PAGE_SIZE)
+ const needle = query.trim().toLowerCase()
+
+ // biome-ignore lint/correctness/useExhaustiveDependencies: reset paging per query
+ useEffect(() => {
+ setVisibleCount(GRID_PAGE_SIZE)
+ }, [needle])
+
+ // Connected first, then connectable, then "coming soon"/desktop-only.
+ const matches = useMemo(() => {
+ const found = entries.filter(
+ (entry) =>
+ !excludeSlugs?.has(entrySlug(entry)) &&
+ (!needle || entryMatchesQuery(entry, needle)),
+ )
+ return found.sort(
+ (a, b) =>
+ Number(isEntryConnected(b)) - Number(isEntryConnected(a)) ||
+ Number(isEntrySetUppable(b)) - Number(isEntrySetUppable(a)),
+ )
+ }, [entries, excludeSlugs, isEntryConnected, needle])
+
+ if (loadError) {
+ if (suppressEmpty) return null
+ return (
+
+ The MCP directory couldn't be loaded. Refresh to try again.
+
+ )
+ }
+ if (entries.length === 0) {
+ if (suppressEmpty) return null
+ return (
+
+
+ )
+ }
+ if (matches.length === 0) {
+ if (suppressEmpty) return null
+ return (
+
+ No integrations match “{query.trim()}”.
+
+ )
+ }
+ return (
+
+
+ {matches.slice(0, visibleCount).map((entry) => (
+
+ {visibleCount < matches.length ? (
+
setVisibleCount((count) => count + GRID_PAGE_SIZE)}
+ className="mx-auto flex h-9 cursor-pointer items-center rounded-full border border-[#2A313C] px-5 text-[12px] font-semibold text-[#D4D4D8] transition-colors hover:border-[#3A4150] hover:text-[#FAFAFA]"
+ >
+ Show {Math.min(GRID_PAGE_SIZE, matches.length - visibleCount)} more ·{" "}
+ {visibleCount} of {matches.length.toLocaleString()}
+
+ ) : null}
+
+
+interface ClaudeFileDocument {
+ documentId: string
+ content: string
+ metadata: ClaudeFileMetadata
+}
+
/**
* Claude Memory Tool - Client-side implementation
* Maps Claude's memory tool commands to supermemory document operations
@@ -44,6 +52,7 @@ export interface MemoryToolResult {
export class ClaudeMemoryTool {
private client: Supermemory
private containerTags: string[]
+ private scopeContainerTags: [string, ...string[]]
private memoryContainerPrefix: string
/**
@@ -68,6 +77,7 @@ export class ClaudeMemoryTool {
// Get base container tags and add memory-specific tag
const baseContainerTags = getContainerTags(config)
+ this.scopeContainerTags = baseContainerTags
this.containerTags = [...baseContainerTags, this.memoryContainerPrefix]
}
@@ -193,44 +203,89 @@ export class ClaudeMemoryTool {
*/
private async listDirectory(dirPath: string): Promise {
try {
- // Search for all memory files
- const response = await this.client.search({
- q: "*", // Search for all
- ...(this.containerTags[0]
- ? { containerTag: this.containerTags[0] }
- : {}),
- limit: 100, // Get many files (max allowed)
- searchMode: "hybrid",
- })
+ // Document search returns ranked chunks, not a complete inventory. Walk
+ // every page of the document-list endpoint so files cannot disappear
+ // from a directory merely because they did not rank in a search page.
+ const documents: Supermemory.DocumentListResponse.Memory[] = []
+ let page = 1
- if (!response.results) {
- return {
- success: true,
- content: `Directory: ${dirPath}\n(empty)`,
- }
+ while (true) {
+ const response = await this.client.documents.list({
+ containerTags: this.scopeContainerTags,
+ filters: {
+ AND: [
+ { key: "claude_memory_type", value: "file" },
+ {
+ key: "file_path",
+ value: dirPath,
+ filterType: "string_contains",
+ },
+ ],
+ },
+ includeContent: false,
+ limit: 100,
+ page,
+ })
+
+ documents.push(...response.memories)
+
+ if (page >= response.pagination.totalPages) break
+ page += 1
}
// Filter files that match the directory path and extract relative paths
const files: string[] = []
const dirs = new Set()
+ const candidates: Array<{
+ document: Supermemory.DocumentListResponse.Memory
+ filePath: string
+ }> = []
- for (const result of response.results) {
- // Get the file path from metadata (since customId is normalized)
- const filePath = result.metadata?.file_path as string
- if (!filePath || !filePath.startsWith(dirPath)) continue
+ for (const document of documents) {
+ if (!this.isDocumentInConfiguredScope(document)) continue
- // Get relative path from directory
- const relativePath = filePath.substring(dirPath.length)
- if (!relativePath) continue
+ const filePath = this.getDocumentFilePath(document)
+ if (!filePath || !filePath.startsWith(dirPath)) {
+ continue
+ }
+ candidates.push({ document, filePath })
+ }
- // If path contains /, it's in a subdirectory
- const slashIndex = relativePath.indexOf("/")
- if (slashIndex > 0) {
- // It's a subdirectory
- dirs.add(`${relativePath.substring(0, slashIndex)}/`)
- } else if (relativePath !== "") {
- // It's a file in this directory
- files.push(relativePath)
+ // Full GETs are required to verify hidden project tags. Keep them bounded
+ // so large directories do not become a long serial chain or a burst of
+ // unbounded requests.
+ const verificationBatchSize = 8
+ for (
+ let index = 0;
+ index < candidates.length;
+ index += verificationBatchSize
+ ) {
+ const batch = candidates.slice(index, index + verificationBatchSize)
+ const verified = await Promise.all(
+ batch.map(async (candidate) =>
+ (await this.isDirectoryDocumentInExactScope(candidate.document))
+ ? candidate
+ : undefined,
+ ),
+ )
+
+ for (const candidate of verified) {
+ if (!candidate) continue
+ const { filePath } = candidate
+
+ // Get relative path from directory
+ const relativePath = filePath.substring(dirPath.length)
+ if (!relativePath) continue
+
+ // If path contains /, it's in a subdirectory
+ const slashIndex = relativePath.indexOf("/")
+ if (slashIndex > 0) {
+ // It's a subdirectory
+ dirs.add(`${relativePath.substring(0, slashIndex)}/`)
+ } else if (relativePath !== "") {
+ // It's a file in this directory
+ files.push(relativePath)
+ }
}
}
@@ -264,10 +319,8 @@ export class ClaudeMemoryTool {
viewRange?: [number, number],
): Promise {
try {
- // Same lookup as every mutating command: limit 5 so the exact
- // customId match is findable among semantic near-neighbours.
- // With the old limit of 1, a similarly-named file ranking first
- // made this return the wrong file's contents as a success.
+ // Resolve the exact document inside the configured scope so reads and
+ // mutations use the complete stored file, not one ranked search chunk.
const readResult = await this.getFileDocument(filePath)
if (!readResult.success || !readResult.document) {
return {
@@ -278,7 +331,7 @@ export class ClaudeMemoryTool {
const document = readResult.document
- let content: string = document.raw || document.content || ""
+ let content = document.content
// Apply line range if specified
if (viewRange) {
@@ -376,8 +429,7 @@ export class ClaudeMemoryTool {
}
}
- const originalContent =
- readResult.document.raw || readResult.document.content || ""
+ const originalContent = readResult.document.content
// Check if old_str exists in the content
if (!originalContent.includes(oldStr)) {
@@ -435,8 +487,7 @@ export class ClaudeMemoryTool {
}
}
- const originalContent =
- readResult.document.raw || readResult.document.content || ""
+ const originalContent = readResult.document.content
const lines = originalContent.split("\n")
// Validate line number
@@ -490,9 +541,7 @@ export class ClaudeMemoryTool {
}
}
- const documentId =
- readResult.document.documentId ?? this.normalizePathToCustomId(filePath)
- await this.client.documents.delete(documentId)
+ await deleteDocumentById(this.client, readResult.document.documentId)
return {
success: true,
@@ -531,8 +580,7 @@ export class ClaudeMemoryTool {
}
}
- const originalContent =
- readResult.document.raw || readResult.document.content || ""
+ const originalContent = readResult.document.content
const newNormalizedId = this.normalizePathToCustomId(newPath)
// Create new document with new path
@@ -552,8 +600,7 @@ export class ClaudeMemoryTool {
// customId — the add above already replaced the content.
const oldNormalizedId = this.normalizePathToCustomId(oldPath)
if (oldNormalizedId !== newNormalizedId) {
- const oldDocumentId = readResult.document.documentId ?? oldNormalizedId
- await this.client.documents.delete(oldDocumentId)
+ await deleteDocumentById(this.client, readResult.document.documentId)
}
return {
@@ -573,48 +620,124 @@ export class ClaudeMemoryTool {
*/
private async getFileDocument(filePath: string): Promise<{
success: boolean
- document?: any
+ document?: ClaudeFileDocument
error?: string
}> {
try {
const normalizedId = this.normalizePathToCustomId(filePath)
+ let page = 1
+ const candidates = new Map<
+ string,
+ Supermemory.DocumentListResponse.Memory
+ >()
- const response = await this.client.search({
- q: normalizedId,
- ...(this.containerTags[0]
- ? { containerTag: this.containerTags[0] }
- : {}),
- limit: 5,
- searchMode: "hybrid",
- })
+ // customId values are only unique within an exact container-tag set in
+ // Mono. Resolve the matching document inside this tool's configured
+ // scope before fetching by internal ID; a direct get(customId) can pick
+ // another project/user's same-named file.
+ while (true) {
+ const response = await this.client.documents.list({
+ containerTags: this.scopeContainerTags,
+ filters: {
+ AND: [
+ { key: "claude_memory_type", value: "file" },
+ { key: "file_path", value: filePath },
+ ],
+ },
+ includeContent: false,
+ limit: 100,
+ page,
+ })
- // Only accept the exact customId match. Falling back to the top
- // semantic hit would let callers read — and worse, modify or
- // delete — a different file than the one they asked for.
- const match = response.results?.find(
- (r) =>
- r.id === normalizedId ||
- r.documents?.some((d) => d.id === normalizedId),
- )
+ for (const document of response.memories) {
+ if (
+ document.customId === normalizedId &&
+ this.getDocumentFilePath(document) === filePath &&
+ this.isDocumentInConfiguredScope(document)
+ ) {
+ candidates.set(document.id, document)
+ }
+ }
- if (!match) {
+ if (page >= response.pagination.totalPages) break
+ page += 1
+ }
+
+ const exactMatches: Array<{
+ candidate: Supermemory.DocumentListResponse.Memory
+ document: Supermemory.DocumentGetResponse
+ }> = []
+ let hasUnverifiedCandidate = false
+ for (const candidate of candidates.values()) {
+ let document: Supermemory.DocumentGetResponse
+ try {
+ document = await this.client.documents.get(candidate.id)
+ } catch (error) {
+ if (error instanceof Supermemory.NotFoundError) continue
+ throw error
+ }
+
+ if (document.id !== candidate.id) {
+ hasUnverifiedCandidate = true
+ continue
+ }
+ if (
+ document.customId !== normalizedId ||
+ this.getDocumentFilePath(document) !== filePath ||
+ !this.hasExactContainerTags(document.containerTags)
+ ) {
+ continue
+ }
+
+ exactMatches.push({ candidate, document })
+ }
+
+ if (exactMatches.length === 0) {
return {
success: false,
error: `File not found: ${filePath}`,
}
}
+ if (exactMatches.length > 1) {
+ return {
+ success: false,
+ error: `File path is ambiguous in the configured container scope: ${filePath}`,
+ }
+ }
+ if (hasUnverifiedCandidate) {
+ return {
+ success: false,
+ error: `File path could not be resolved unambiguously in the configured container scope: ${filePath}`,
+ }
+ }
- const content = match.chunk || match.memory || ""
- const documentId = match.documents?.[0]?.id ?? match.id
+ const match = exactMatches[0]
+ if (!match) {
+ return { success: false, error: `File not found: ${filePath}` }
+ }
+ const { candidate, document } = match
+ const content =
+ typeof document.content === "string"
+ ? document.content
+ : typeof document.raw === "string"
+ ? document.raw
+ : undefined
+ if (content === undefined) {
+ return {
+ success: false,
+ error: `File content unavailable: ${filePath}`,
+ }
+ }
+ const metadata =
+ document.metadata &&
+ typeof document.metadata === "object" &&
+ !Array.isArray(document.metadata)
+ ? (document.metadata as ClaudeFileMetadata)
+ : {}
return {
success: true,
- document: {
- documentId,
- content,
- raw: content,
- metadata: match.metadata,
- },
+ document: { documentId: candidate.id, content, metadata },
}
} catch (error) {
return {
@@ -624,6 +747,60 @@ export class ClaudeMemoryTool {
}
}
+ private getDocumentFilePath(document: {
+ metadata: unknown
+ }): string | undefined {
+ const metadata = document.metadata
+ if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+ return undefined
+ }
+ const metadataRecord = metadata as Record
+
+ return typeof metadataRecord.file_path === "string"
+ ? metadataRecord.file_path
+ : undefined
+ }
+
+ private isDocumentInConfiguredScope(
+ document: Supermemory.DocumentListResponse.Memory,
+ ): boolean {
+ const documentTags = document.containerTags ?? []
+ const expectedTags = this.containerTags.filter(
+ (tag) => !tag.startsWith("sm_project_"),
+ )
+
+ return (
+ documentTags.length === expectedTags.length &&
+ documentTags.every((tag, index) => tag === expectedTags[index])
+ )
+ }
+
+ private async isDirectoryDocumentInExactScope(
+ document: Supermemory.DocumentListResponse.Memory,
+ ): Promise {
+ try {
+ // Mono strips internal project tags from every list response, so only a
+ // full get can prove that no hidden tags change this document's scope.
+ const fullDocument = await this.client.documents.get(document.id)
+ return (
+ fullDocument.id === document.id &&
+ this.hasExactContainerTags(fullDocument.containerTags)
+ )
+ } catch (error) {
+ if (!(error instanceof Supermemory.NotFoundError)) throw error
+ // A document can disappear between list and get. Skip stale entries
+ // instead of failing the entire directory view.
+ return false
+ }
+ }
+
+ private hasExactContainerTags(containerTags?: string[]): boolean {
+ return (
+ containerTags?.length === this.containerTags.length &&
+ containerTags.every((tag, index) => tag === this.containerTags[index])
+ )
+ }
+
/**
* Validate that path starts with /memories for security
*/
diff --git a/packages/tools/src/openai/tools.ts b/packages/tools/src/openai/tools.ts
index 49b5c88a..06a26935 100644
--- a/packages/tools/src/openai/tools.ts
+++ b/packages/tools/src/openai/tools.ts
@@ -4,6 +4,7 @@ import {
DEFAULT_VALUES,
PARAMETER_DESCRIPTIONS,
TOOL_DESCRIPTIONS,
+ deleteDocumentByIdentifier,
getContainerTags,
} from "../tools-shared"
import { forgetMemoryRequest } from "../shared/forget-memory"
@@ -14,7 +15,9 @@ import type { SupermemoryToolsConfig } from "../types"
*/
export interface MemorySearchResult {
success: boolean
- results?: Awaited>["results"]
+ results?: Awaited<
+ ReturnType
+ >["results"]
count?: number
error?: string
}
@@ -31,7 +34,7 @@ export interface ProfileResult {
static: string[]
dynamic: string[]
}
- searchResults?: Awaited>
+ searchResults?: Awaited>["searchResults"]
error?: string
}
@@ -159,6 +162,10 @@ export const memoryToolSchemas = {
type: "string",
description: PARAMETER_DESCRIPTIONS.documentId,
},
+ containerTag: {
+ type: "string",
+ description: PARAMETER_DESCRIPTIONS.documentContainerTag,
+ },
},
required: ["documentId"],
},
@@ -248,12 +255,12 @@ export function createSearchMemoriesFunction(
limit?: number
}): Promise {
try {
- const response = await client.search({
+ const response = await client.search.documents({
q: informationToGet,
- ...(containerTags[0] ? { containerTag: containerTags[0] } : {}),
+ containerTags,
limit,
- threshold: DEFAULT_VALUES.chunkThreshold,
- searchMode: "hybrid",
+ chunkThreshold: DEFAULT_VALUES.chunkThreshold,
+ includeFullDocs,
})
return {
@@ -363,10 +370,12 @@ export function createDocumentListFunction(
page?: number
}): Promise {
try {
- const tag = containerTag || containerTags[0]
+ const scopeTags: [string, ...string[]] = containerTag
+ ? [containerTag]
+ : containerTags
const response = await client.documents.list({
- containerTags: [tag],
+ containerTags: scopeTags,
limit: limit || DEFAULT_VALUES.limit,
...(page !== undefined && { page }),
})
@@ -392,15 +401,20 @@ export function createDocumentDeleteFunction(
apiKey: string,
config?: SupermemoryToolsConfig,
) {
- const { client } = createClient(apiKey, config)
+ const { client, containerTags } = createClient(apiKey, config)
return async function documentDelete({
documentId,
+ containerTag,
}: {
documentId: string
+ containerTag?: string
}): Promise {
try {
- await client.documents.delete(documentId)
+ const scopeTags: [string, ...string[]] = containerTag
+ ? [containerTag]
+ : containerTags
+ await deleteDocumentByIdentifier(client, documentId, scopeTags)
return {
success: true,
diff --git a/packages/tools/src/tool-operations.test.ts b/packages/tools/src/tool-operations.test.ts
index 8ec46fa0..c6152021 100644
--- a/packages/tools/src/tool-operations.test.ts
+++ b/packages/tools/src/tool-operations.test.ts
@@ -2,18 +2,18 @@ import { beforeEach, describe, expect, it, vi } from "vitest"
// Mock the Supermemory SDK (same pattern as claude-memory.test.ts) so tool
// executions can be verified deterministically without network access.
-const documentsDelete = vi.fn()
+const documentsDeleteBulk = vi.fn()
+const documentsGet = vi.fn()
const documentsList = vi.fn()
-const searchMock = vi.fn()
const clientAdd = vi.fn()
vi.mock("supermemory", () => {
return {
default: class MockSupermemory {
- search = searchMock
add = clientAdd
documents = {
- delete: documentsDelete,
+ deleteBulk: documentsDeleteBulk,
+ get: documentsGet,
list: documentsList,
add: vi.fn(),
}
@@ -35,12 +35,20 @@ function executeTool(tool: unknown, args: Record) {
}
beforeEach(() => {
- documentsDelete.mockReset().mockResolvedValue(undefined)
+ documentsDeleteBulk.mockReset().mockResolvedValue({
+ success: true,
+ deletedCount: 1,
+ errors: [],
+ })
+ documentsGet.mockReset().mockResolvedValue({
+ id: "doc_123",
+ customId: "doc_123",
+ containerTags: ["sm_project_default"],
+ })
documentsList.mockReset().mockResolvedValue({
memories: [{ id: "doc_1", title: "Doc one" }],
pagination: { currentPage: 1, totalItems: 1, totalPages: 1 },
})
- searchMock.mockReset()
clientAdd.mockReset().mockResolvedValue({ id: "doc_new" })
vi.unstubAllGlobals()
})
@@ -53,7 +61,8 @@ describe("documentDelete", () => {
}
expect(result.success).toBe(true)
- expect(documentsDelete).toHaveBeenCalledWith("doc_123")
+ expect(documentsGet).toHaveBeenCalledWith("doc_123")
+ expect(documentsDeleteBulk).toHaveBeenCalledWith({ ids: ["doc_123"] })
})
})
@@ -177,16 +186,30 @@ describe("memoryForget", () => {
describe("ClaudeMemoryTool", () => {
const FILE_PATH = "/memories/prefs.txt"
const CUSTOM_ID = "memories_prefs_txt"
+ const DOCUMENT_ID = "doc_file_1"
function mockFileDocument(content: string) {
- searchMock.mockResolvedValue({
- results: [
+ const metadata = {
+ claude_memory_type: "file",
+ file_path: FILE_PATH,
+ }
+ documentsList.mockResolvedValue({
+ memories: [
{
- id: CUSTOM_ID,
- chunk: content,
- metadata: { file_path: FILE_PATH },
+ id: DOCUMENT_ID,
+ customId: CUSTOM_ID,
+ containerTags: ["claude_memory"],
+ metadata,
},
],
+ pagination: { currentPage: 1, totalItems: 1, totalPages: 1 },
+ })
+ documentsGet.mockResolvedValue({
+ id: DOCUMENT_ID,
+ customId: CUSTOM_ID,
+ containerTags: ["sm_project_default", "claude_memory"],
+ content,
+ metadata,
})
}
@@ -247,7 +270,7 @@ describe("ClaudeMemoryTool", () => {
})
expect(result.success).toBe(true)
- expect(documentsDelete).toHaveBeenCalledWith(CUSTOM_ID)
+ expect(documentsDeleteBulk).toHaveBeenCalledWith({ ids: [DOCUMENT_ID] })
})
it("rename removes the old document after creating the new one", async () => {
@@ -264,6 +287,6 @@ describe("ClaudeMemoryTool", () => {
expect(clientAdd).toHaveBeenCalledWith(
expect.objectContaining({ customId: "memories_renamed_txt" }),
)
- expect(documentsDelete).toHaveBeenCalledWith(CUSTOM_ID)
+ expect(documentsDeleteBulk).toHaveBeenCalledWith({ ids: [DOCUMENT_ID] })
})
})
diff --git a/packages/tools/src/tools-shared.ts b/packages/tools/src/tools-shared.ts
index cbb1c1a7..dffc7093 100644
--- a/packages/tools/src/tools-shared.ts
+++ b/packages/tools/src/tools-shared.ts
@@ -2,48 +2,51 @@
* Shared constants and descriptions for Supermemory tools
*/
+import type Supermemory from "supermemory"
import type { MemoryMode } from "./shared/types"
// Tool descriptions
export const TOOL_DESCRIPTIONS = {
searchMemories:
- "Search (recall) stored memories for facts, preferences, history, and context about the user or any topic. Use proactively before answering whenever memory could help — do not wait for the user to explicitly ask you to search or recall. Search when the question touches personal context, past conversations, preferences, projects, people, plans, or anything you may have learned before. Results include memory/chunk IDs — use those IDs with memoryForget to remove a specific learned fact.",
+ "Search stored source documents for relevant facts, preferences, history, and other context. Use when explicitly asked to search or recall, or when past context could materially improve the response; do not invoke reflexively on every turn. Results contain document IDs and matching text chunks, not profile-memory IDs for memoryForget.",
addMemory:
"Add (remember) memories/details/information about the user or other facts or entities. Run when explicitly asked or when the user mentions any information generalizable beyond the context of the current conversation.",
getProfile:
- "Get user profile containing static memories (permanent facts) and dynamic memories (recent context). Optionally include search results by providing a query. Profile and search result entries may include memory IDs useful for memoryForget.",
+ "Get user profile containing static memories (permanent facts) and dynamic memories (recent context). Profile entries are text without IDs. Provide a query to include searchResults, whose memory entries may include IDs usable with memoryForget.",
documentList:
- "List stored source documents (conversations, URLs, files, pasted text) with pagination. Returns document IDs for documentDelete — not memory IDs for memoryForget. Use to browse raw stored content before permanently removing a source.",
+ "List stored source documents (conversations, URLs, files, pasted text) with pagination. Configured container tags are treated as the default union; an optional containerTag replaces that union with one tag for this operation. Returns document metadata and IDs for documentDelete, not raw document content or memory IDs for memoryForget.",
documentDelete:
- "Permanently delete a stored document and ALL memories extracted from it (hard delete). Use document IDs from documentList. Use when the user wants to remove an entire conversation, file, URL, or other source — not when correcting a single learned fact (use memoryForget for that).",
+ "Permanently delete a stored source document. Memories extracted from that source are soft-forgotten so they no longer appear in profile or search; they are not hard-deleted. Use a document ID or customId when removing an entire conversation, file, URL, or other source. The effective scope is the configured container-tag union, or the explicit one-tag override; if documentList used an override, pass the same value here. To forget one learned fact, use memoryForget instead.",
documentAdd:
"Store a source document for asynchronous processing and automatic memory extraction. Use when the user gives you raw content to ingest — a pasted text blob, conversation transcript, chat history, notes, URL, article link, or other substantial text — rather than a single atomic fact (use addMemory for one short generalizable sentence). The document is queued immediately; Supermemory post-processes it in the background (chunking, embedding, indexing) and extracts profile memories automatically — you do not need to call addMemory for facts buried inside the document. Good for saving full conversations, long-form notes, knowledge-base articles, meeting transcripts, or any large body of text the user wants remembered beyond this chat turn. Processing may take a moment; extracted memories appear in profile/search after indexing completes.",
memoryForget:
- "Soft-delete a single extracted profile memory (a learned fact) so it no longer appears in profile or search. Does NOT delete source documents. Provide memoryId (preferred — from searchMemories or getProfile) OR memoryContent for an exact text match. Use when the user retracts or corrects a specific fact (e.g. 'forget I like tea', 'that's wrong'). To remove an entire conversation or file, use documentDelete instead.",
+ "Soft-forget a single extracted profile memory (a learned fact) so it no longer appears in profile or search. Does NOT delete source documents. Provide memoryId from query-backed getProfile searchResults, or memoryContent for an exact text match; document and chunk IDs from searchMemories are not valid. Use when the user retracts or corrects a specific fact. To remove an entire source, use documentDelete instead.",
} as const
// Parameter descriptions
export const PARAMETER_DESCRIPTIONS = {
informationToGet:
- "What to look up in memory — keywords from the user's message, topic, entity names, or question phrasing. Search even when the user did not explicitly ask you to recall.",
+ "What to look up in stored context — keywords from the user's message, topic, entity names, or question phrasing.",
includeFullDocs:
"Whether to include the full document content in the response. Defaults to true for better AI context.",
limit: "Maximum number of results to return",
memory:
"The text content of the memory to add. This should be a single sentence or a short paragraph.",
containerTag: "Tag to filter/scope the operation (e.g., user ID, project ID)",
+ documentContainerTag:
+ "Optional one-tag scope override. When deleting a document returned by documentList with a containerTag override, pass the same value here. In strict mode, pass null to use the configured union.",
query: "Optional search query to include relevant search results",
page: "Page number to fetch, 1-based (default: 1)",
documentId:
- "Document ID from documentList — permanently deletes the source document and all extracted memories. Not a profile memory ID.",
+ "Document ID from documentList, or the document customId. Permanently deletes the source document and soft-forgets its extracted memories. If documentList used a containerTag override, pass it again. Not a profile-memory ID.",
content:
"Document body to store — plain text, a conversation transcript, a long pasted blob, or a URL to a webpage/PDF/image/video. Content is queued and memories are extracted automatically after background processing; do not split into addMemory calls.",
title: "Optional title for the document",
description: "Optional description for the document",
memoryId:
- "Profile memory ID from searchMemories or getProfile — soft-deletes one learned fact via memoryForget. Not a document ID.",
+ "Profile-memory ID from query-backed getProfile searchResults. Soft-forgets one learned fact; document and chunk IDs from searchMemories are not valid.",
memoryContent:
- "Exact text of the profile memory to forget (alternative to memoryId). Must match precisely; if unsure, search first and use memoryId.",
+ "Exact text of the profile memory to forget (alternative to memoryId). Must match precisely; if unsure, query getProfile and use a search-result memory ID.",
reason: "Optional reason recorded when forgetting (e.g. outdated, user correction)",
} as const
@@ -57,7 +60,7 @@ export const DEFAULT_VALUES = {
// Container tag constants
export const CONTAINER_TAG_CONSTANTS = {
projectPrefix: "sm_project_",
- defaultTags: ["sm_project_default"] as string[],
+ defaultTags: ["sm_project_default"] as const,
} as const
/**
@@ -66,16 +69,167 @@ export const CONTAINER_TAG_CONSTANTS = {
export function getContainerTags(config?: {
projectId?: string
containerTags?: string[]
-}): string[] {
+}): [string, ...string[]] {
if (config?.projectId !== undefined && config.containerTags !== undefined) {
throw new Error(
"Supermemory tools config accepts either projectId or containerTags, not both.",
)
}
- if (config?.projectId) {
+ if (config?.projectId !== undefined) {
+ if (config.projectId.trim() === "") {
+ throw new Error("Supermemory tools config requires a non-empty projectId.")
+ }
return [`${CONTAINER_TAG_CONSTANTS.projectPrefix}${config.projectId}`]
}
- return config?.containerTags ?? CONTAINER_TAG_CONSTANTS.defaultTags
+ if (config?.containerTags !== undefined) {
+ const [firstTag, ...remainingTags] = config.containerTags
+ if (
+ firstTag === undefined ||
+ config.containerTags.some((tag) => tag.trim() === "")
+ ) {
+ throw new Error(
+ "Supermemory tools config requires at least one non-empty containerTag.",
+ )
+ }
+ return [firstTag, ...remainingTags]
+ }
+ return [...CONTAINER_TAG_CONSTANTS.defaultTags]
+}
+
+/** Delete exactly one document by its internal ID. */
+export async function deleteDocumentById(
+ client: Supermemory,
+ documentId: string,
+): Promise {
+ const response = await client.documents.deleteBulk({ ids: [documentId] })
+ if (response.success && response.deletedCount === 1) return
+
+ const detail = response.errors?.find((error) => error.id === documentId)?.error
+ throw new Error(
+ detail
+ ? `Failed to delete document ${documentId}: ${detail}`
+ : `Failed to delete document ${documentId}: expected one deletion, received ${response.deletedCount}`,
+ )
+}
+
+/**
+ * Resolve an internal ID or customId inside the effective container-tag union,
+ * then delete the exact internal document ID. Internal IDs take precedence over
+ * customId matches.
+ */
+export async function deleteDocumentByIdentifier(
+ client: Supermemory,
+ documentIdentifier: string,
+ containerTags: readonly [string, ...string[]],
+): Promise {
+ const directMatch = await getDocumentIfFound(client, documentIdentifier)
+ if (
+ directMatch?.id === documentIdentifier &&
+ hasContainerTagOverlap(directMatch.containerTags, containerTags)
+ ) {
+ await deleteDocumentById(client, directMatch.id)
+ return
+ }
+
+ const candidateIds = new Set()
+ let hasInternalIdCandidate = false
+ let page = 1
+ while (true) {
+ const response = await client.documents.list({
+ containerTags: [...containerTags],
+ includeContent: false,
+ limit: 100,
+ page,
+ })
+ for (const document of response.memories) {
+ if (document.id === documentIdentifier) {
+ hasInternalIdCandidate = true
+ }
+ if (
+ document.id === documentIdentifier ||
+ document.customId === documentIdentifier
+ ) {
+ candidateIds.add(document.id)
+ }
+ }
+ if (page >= response.pagination.totalPages) break
+ page += 1
+ }
+
+ let exactIdMatch: string | undefined
+ let hasUnverifiedCandidate = false
+ const customIdMatches: string[] = []
+ for (const candidateId of candidateIds) {
+ const document = await getDocumentIfFound(client, candidateId)
+ if (document?.id !== candidateId) {
+ hasUnverifiedCandidate = true
+ continue
+ }
+ if (!hasContainerTagOverlap(document.containerTags, containerTags)) {
+ continue
+ }
+ if (document.id === documentIdentifier) {
+ exactIdMatch = document.id
+ break
+ }
+ if (document.customId === documentIdentifier) {
+ customIdMatches.push(document.id)
+ } else {
+ hasUnverifiedCandidate = true
+ }
+ }
+
+ if (exactIdMatch) {
+ await deleteDocumentById(client, exactIdMatch)
+ return
+ }
+ if (hasInternalIdCandidate) {
+ throw new Error(
+ `Document ID ${documentIdentifier} could not be verified safely in the configured container scope.`,
+ )
+ }
+ if (hasUnverifiedCandidate) {
+ throw new Error(
+ `Document identifier ${documentIdentifier} could not be resolved unambiguously in the configured container scope.`,
+ )
+ }
+ if (customIdMatches.length === 1) {
+ await deleteDocumentById(client, customIdMatches[0] as string)
+ return
+ }
+ if (customIdMatches.length > 1) {
+ throw new Error(
+ `Document customId ${documentIdentifier} is ambiguous in the configured container scope.`,
+ )
+ }
+ throw new Error(
+ `Document ${documentIdentifier} was not found in the configured container scope.`,
+ )
+}
+
+async function getDocumentIfFound(client: Supermemory, documentId: string) {
+ try {
+ return await client.documents.get(documentId)
+ } catch (error) {
+ if (isNotFoundError(error)) return undefined
+ throw error
+ }
+}
+
+function isNotFoundError(error: unknown): boolean {
+ return (
+ typeof error === "object" &&
+ error !== null &&
+ "status" in error &&
+ error.status === 404
+ )
+}
+
+function hasContainerTagOverlap(
+ actual: string[] | undefined,
+ expected: readonly string[],
+): boolean {
+ return actual?.some((tag) => expected.includes(tag)) ?? false
}
/**
diff --git a/packages/tools/src/voltagent/middleware.ts b/packages/tools/src/voltagent/middleware.ts
index bf771726..7e788c3d 100644
--- a/packages/tools/src/voltagent/middleware.ts
+++ b/packages/tools/src/voltagent/middleware.ts
@@ -18,7 +18,11 @@ import {
type Logger,
type MemoryMode,
} from "../shared"
-import type { SupermemoryVoltAgent, VoltAgentMessage } from "./types"
+import type {
+ SearchFilters,
+ SupermemoryVoltAgent,
+ VoltAgentMessage,
+} from "./types"
/**
* Context for Supermemory middleware operations.
@@ -47,7 +51,7 @@ export interface SupermemoryMiddlewareContext {
limit?: number
rerank?: boolean
rewriteQuery?: boolean
- filters?: { OR: Array } | { AND: Array }
+ filters?: SearchFilters
include?: {
chunks?: boolean
documents?: boolean
@@ -258,23 +262,7 @@ export const enhanceMessagesWithMemories = async (
if (useAdvancedSearch && ctx.mode !== "profile") {
ctx.logger.info("Using advanced search with custom parameters")
- const searchParams: {
- q: string
- containerTag: string
- threshold?: number
- limit?: number
- rerank?: boolean
- rewriteQuery?: boolean
- filters?: { OR: Array } | { AND: Array }
- include?: {
- chunks?: boolean
- documents?: boolean
- forgottenMemories?: boolean
- relatedMemories?: boolean
- summaries?: boolean
- }
- searchMode?: "memories" | "documents" | "hybrid"
- } = {
+ const searchParams: Supermemory.SearchParams = {
q: queryText,
containerTag: ctx.containerTag,
}
@@ -288,31 +276,32 @@ export const enhanceMessagesWithMemories = async (
if (ctx.include !== undefined) searchParams.include = ctx.include
if (ctx.searchMode !== undefined) searchParams.searchMode = ctx.searchMode
- const response = await ctx.client.search.memories(searchParams)
+ const response = await ctx.client.search(searchParams)
// Hybrid search returns both memory entries (`memory` field) and
- // document chunks (`chunk` field). Handle both.
- type SearchResult = {
- memory?: string
- chunk?: string
- metadata?: Record
- }
- const formattedMemories = response.results
- .map((result: SearchResult) => {
- const text = result.memory || result.chunk
- return text ? `- ${text}` : null
- })
- .filter(Boolean)
+ // document chunks (`chunk` field). Normalize both for prompt templates.
+ const searchResults = response.results.flatMap((result) => {
+ const memory = result.memory ?? result.chunk
+ if (!memory) {
+ return []
+ }
+
+ return [
+ {
+ memory,
+ ...(result.metadata ? { metadata: result.metadata } : {}),
+ },
+ ]
+ })
+ const formattedMemories = searchResults
+ .map((result) => `- ${result.memory}`)
.join("\n")
memories = ctx.promptTemplate
? ctx.promptTemplate({
userMemories: "",
generalSearchMemories: formattedMemories,
- searchResults: response.results as Array<{
- memory: string
- metadata?: Record
- }>,
+ searchResults,
})
: `The following are relevant memories and context about this user retrieved from previous interactions. Use these to personalize your response:\n\n${formattedMemories}`
} else {
diff --git a/packages/tools/src/voltagent/types.ts b/packages/tools/src/voltagent/types.ts
index cc5350ea..e6524ebc 100644
--- a/packages/tools/src/voltagent/types.ts
+++ b/packages/tools/src/voltagent/types.ts
@@ -5,6 +5,7 @@
* Supermemory by providing hooks that inject memories before LLM calls.
*/
+import type Supermemory from "supermemory"
import type {
PromptTemplate,
MemoryMode,
@@ -58,7 +59,7 @@ export interface SupermemoryVoltAgent extends SupermemoryBaseOptions {
/**
* Advanced filters to apply to the search using AND/OR logic.
- * Example: { OR: [{ metadata: { type: "note" } }, { metadata: { type: "conversation" } }] }
+ * Example: { OR: [{ key: "type", value: "note" }, { key: "type", value: "conversation" }] }
*
* Note: Only effective when mode is "query" or "full". Ignored in "profile" mode.
*/
@@ -99,7 +100,7 @@ export interface SupermemoryVoltAgent extends SupermemoryBaseOptions {
/**
* Advanced search filters using AND/OR logic
*/
-export type SearchFilters = { OR: Array } | { AND: Array }
+export type SearchFilters = NonNullable
/**
* Options for including additional data in search results
From 7153801f11dfdb50aeed6c4e0840ce79ccc7f805 Mon Sep 17 00:00:00 2001
From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com>
Date: Sat, 22 Aug 2026 06:46:13 +0000
Subject: [PATCH 37/37] fix(tools): resolve lint and format errors
- Replace `as any` with typed assertion in claude-memory.ts
- Apply Biome formatting fixes
Co-Authored-By: Claude Opus 4.5
---
packages/tools/src/claude-memory.test.ts | 34 +++++++++++++-----------
packages/tools/src/claude-memory.ts | 2 +-
packages/tools/src/openai/tools.ts | 4 +--
packages/tools/src/tools-shared.ts | 11 +++++---
4 files changed, 28 insertions(+), 23 deletions(-)
diff --git a/packages/tools/src/claude-memory.test.ts b/packages/tools/src/claude-memory.test.ts
index afe16dcf..7337441a 100644
--- a/packages/tools/src/claude-memory.test.ts
+++ b/packages/tools/src/claude-memory.test.ts
@@ -39,7 +39,7 @@ const NEIGHBOUR_DOCUMENT = {
content: "backup stuff",
}
-function mockDocuments(documents: typeof FILE_DOCUMENT[]) {
+function mockDocuments(documents: (typeof FILE_DOCUMENT)[]) {
documentsListMock.mockResolvedValue({
memories: documents.map((document) => ({
id: document.id,
@@ -191,20 +191,22 @@ describe("ClaudeMemoryTool str_replace replacement literalness", () => {
tool = new ClaudeMemoryTool("test-api-key")
})
- it.each(["$&", "$'", "$`", "$$"])(
- "stores %s literally instead of expanding it as a replacement pattern",
- async (dollarSequence) => {
- const result = await tool.handleCommand({
- command: "str_replace",
- path: FILE_PATH,
- old_str: "line3",
- new_str: `price is ${dollarSequence} today`,
- })
+ it.each([
+ "$&",
+ "$'",
+ "$`",
+ "$$",
+ ])("stores %s literally instead of expanding it as a replacement pattern", async (dollarSequence) => {
+ const result = await tool.handleCommand({
+ command: "str_replace",
+ path: FILE_PATH,
+ old_str: "line3",
+ new_str: `price is ${dollarSequence} today`,
+ })
- expect(result.success).toBe(true)
- expect(addMock).toHaveBeenCalledTimes(1)
- const stored = addMock.mock.calls[0]?.[0]?.content as string
- expect(stored).toContain(`price is ${dollarSequence} today`)
- },
- )
+ expect(result.success).toBe(true)
+ expect(addMock).toHaveBeenCalledTimes(1)
+ const stored = addMock.mock.calls[0]?.[0]?.content as string
+ expect(stored).toContain(`price is ${dollarSequence} today`)
+ })
})
diff --git a/packages/tools/src/claude-memory.ts b/packages/tools/src/claude-memory.ts
index 3792e9f8..867c4d82 100644
--- a/packages/tools/src/claude-memory.ts
+++ b/packages/tools/src/claude-memory.ts
@@ -150,7 +150,7 @@ export class ClaudeMemoryTool {
default:
return {
success: false,
- error: `Unknown command: ${(command as any).command}`,
+ error: `Unknown command: ${(command as { command: string }).command}`,
}
}
} catch (error) {
diff --git a/packages/tools/src/openai/tools.ts b/packages/tools/src/openai/tools.ts
index 06a26935..22257727 100644
--- a/packages/tools/src/openai/tools.ts
+++ b/packages/tools/src/openai/tools.ts
@@ -15,9 +15,7 @@ import type { SupermemoryToolsConfig } from "../types"
*/
export interface MemorySearchResult {
success: boolean
- results?: Awaited<
- ReturnType
- >["results"]
+ results?: Awaited>["results"]
count?: number
error?: string
}
diff --git a/packages/tools/src/tools-shared.ts b/packages/tools/src/tools-shared.ts
index dffc7093..c0a3b540 100644
--- a/packages/tools/src/tools-shared.ts
+++ b/packages/tools/src/tools-shared.ts
@@ -47,7 +47,8 @@ export const PARAMETER_DESCRIPTIONS = {
"Profile-memory ID from query-backed getProfile searchResults. Soft-forgets one learned fact; document and chunk IDs from searchMemories are not valid.",
memoryContent:
"Exact text of the profile memory to forget (alternative to memoryId). Must match precisely; if unsure, query getProfile and use a search-result memory ID.",
- reason: "Optional reason recorded when forgetting (e.g. outdated, user correction)",
+ reason:
+ "Optional reason recorded when forgetting (e.g. outdated, user correction)",
} as const
// Default values
@@ -77,7 +78,9 @@ export function getContainerTags(config?: {
}
if (config?.projectId !== undefined) {
if (config.projectId.trim() === "") {
- throw new Error("Supermemory tools config requires a non-empty projectId.")
+ throw new Error(
+ "Supermemory tools config requires a non-empty projectId.",
+ )
}
return [`${CONTAINER_TAG_CONSTANTS.projectPrefix}${config.projectId}`]
}
@@ -104,7 +107,9 @@ export async function deleteDocumentById(
const response = await client.documents.deleteBulk({ ids: [documentId] })
if (response.success && response.deletedCount === 1) return
- const detail = response.errors?.find((error) => error.id === documentId)?.error
+ const detail = response.errors?.find(
+ (error) => error.id === documentId,
+ )?.error
throw new Error(
detail
? `Failed to delete document ${documentId}: ${detail}`