Skip to content

feat(tools,docs): add full export and list API helpers for memories (#1653) - #1657

Open
Adityakk9031 wants to merge 3 commits into
supermemoryai:mainfrom
Adityakk9031:feat/self-hosted-memories-export
Open

Adityakk9031 wants to merge 3 commits into
supermemoryai:mainfrom
Adityakk9031:feat/self-hosted-memories-export

Conversation

@Adityakk9031

Copy link
Copy Markdown
Contributor

Summary

Resolves #1653

This PR introduces comprehensive listing, exhaustive pagination, and export tools for distilled memories (memory entries) across both self-hosted and cloud Supermemory deployments:

  1. Memory Export & Pagination Utilities (@supermemory/tools):
    • Added listMemoriesRequest: Direct caller for the /v4/memories/list endpoint with container tags, pagination, and sorting.
    • Added fetchAllMemories: Auto-paginating helper that iterates through all pages to retrieve all memory entries for a container tag.
    • Added exportMemoriesAsJson: Full JSON backup serializer with metadata (exportedAt, totalCount, containerTag, baseUrl).
    • Added exportMemoriesAsMarkdown: Human-readable Markdown export format with revision histories and source document references.
  2. CLI Tool (supermemory-export):
    • Added supermemory-export CLI in @supermemory/tools/bin for terminal-based backups (bunx @supermemory/tools supermemory-export --tag user_123 --out backup.json --url http://localhost:6767).
  3. Self-Hosting Documentation:
    • Added a dedicated Backup & Export Guide documenting:
      • The distinction between raw ingested documents (/v3/documents) and extracted memory cards (/v4/memories/list).
      • Why direct disk copying of encrypted local storage (.supermemory/data SMD1 format) is unsupported and how the HTTP API provides a clean, portable backup path.
      • Complete, copy-pasteable export scripts in cURL, Python, TypeScript, and via the CLI.
      • Memory migration guide from self-hosted to cloud platform (POST /v4/memories).
    • Linked from apps/docs/docs.json under Deployment > Supermemory local, and apps/docs/self-hosting/overview.mdx.
  4. Unit Tests:
    • Added 6 unit tests in packages/tools/src/export-memories.test.ts validating request formation, pagination, soft-forgotten memory filtering, and JSON/Markdown outputs.

Testing

  • Ran bun test src/export-memories.test.ts (6 passing).
  • Ran bun test src/tools-shared.test.ts src/export-memories.test.ts (19 passing).
  • Verified bun run ./bin/supermemory-export.ts --help runs and outputs correct usage.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Self-hosted: full export/list API for extracted memories (currently only search-based recall)

1 participant