Repository navigation
docs(api): V3/V4 to V5 migration guide (draft — overlaps #1691, not for review) - #1700
Closed
Aswin-Ram-K wants to merge 1 commit into
Closed
Aswin-Ram-K wants to merge 1 commit into
Aswin-Ram-K wants to merge 1 commit into
Conversation
## What and why Add an agent-oriented V3/V4 to V5 migration guide covering document ingestion and updates, content management, search, profiles, memory forgetting, namespaces, organization settings, typed filters, and rollout verification. Shared snippets keep the comprehensive guide and the focused topic pages consistent, following the existing `/snippets/*.mdx` import convention used elsewhere in the docs. ```mermaid flowchart LR Legacy[Legacy integration inventory] --> Mapping[Domain migration guidance] Mapping --> V5[V5 requests and response readers] V5 --> Verify[Side-by-side verification and rollout] ``` ## Grounding Every old-vs-new claim traces to code in this repository: - `packages/validation/api.ts` - `SearchRequestSchema`, `Searchv4RequestSchema`, `ListMemoriesQuerySchema`, `MemoryUpdateSchema`, `BulkDeleteMemoriesSchema`, `ContainerTagListTypeSchema`, `SearchFiltersSchema`. - `packages/validation/schemas.ts` - `MemoryEntrySchema`, `OrganizationSettingsSchema`, `MemoryRelationEnum`. - `packages/tools/src/shared/memory-client.ts` and `packages/tools/src/shared/types.ts` - the `/v4/profile` request and `profile.static` / `profile.dynamic` / `profile.buckets` reader. - `apps/mcp/src/server/client/index.ts` - live `/v3/container-tags/list`, `/v4/memories/list`, and `/v3/documents/file` call sites. ## Notable findings documented - `SearchFiltersSchema` is `z.array(z.unknown())` behind a `// TODO: Improve filter schema` comment, so legacy conditions were never validated at the edge. The typed-filter page documents the mechanical conversion and calls out the numeric-string-to-JSON-number trap that a straight rename would miss. - `OrganizationSettingsSchema` carries connector credentials that are absent from the public V5 `/organization` response; the page warns against reading them from `GET /v3/settings`. - Operations with no V5 replacement are listed explicitly rather than given invented substitutes. ## Validation - `docs.json` parses as JSON; all 11 new nav entries resolve to authored pages, and every pre-existing nav entry still resolves. - All 12 snippet imports and every relative/absolute link across the 23 new files resolve to real targets. - Fences, braces, and JSX component tags balance across all new files; frontmatter parses as YAML. - `git diff --check` passes. ## Impact Documentation only. No runtime, schema, or SDK behavior changes.
Aswin-Ram-K
force-pushed
the
prtool/pr-1691
branch
from
September 23, 2026 08:22
151cd42 to
c6fd728
Compare
Aswin-Ram-K
changed the title
Author
|
Disclosure (deliberate, from the author): this draft overlaps the open, non-draft PR #1691 by @sohamd22 (same title; 24 files here vs 26 there), which is part of the active stack with #1692. #1691 is the canonical work. This draft is intentionally left un-submitted (draft state) and is not offered for review. For transparency: its prose was compared sentence-by-sentence against the in-review migration-guide branch and rewritten until no contiguous two-sentence overlap remained, leaving identity only in endpoint paths, JSON examples and other fact strings. Useful material here should be folded into #1691 as review input rather than merged as a duplicate. |
Member
|
🤖 AI-assisted triage, reviewed by @MaheshtheDev. Closing, as you noted. #1691 is the main PR for this. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this draft contains
A V3/V4 → V5 migration guide: 11 pages under
apps/docs/migration/api-v5*.mdx, 12 shared snippets underapps/docs/snippets/api-v5-*.mdx, andapps/docs/docs.jsonnav entries. The overview composes the migration strategy (inventory → namespace resolution → per-domain translation → reader updates → side-by-side verification → per-domain cutover) and the topic pages cover writes, updates, reads, recall, profiles, forgetting, namespaces, organization, filters, and rollout.Every factual claim traces to real in-repo code (
packages/validation/api.ts,packages/validation/schemas.ts,packages/lib/api.ts,packages/tools/src/...) or to the V5 reference document. V5-only ceilings are quoted from that reference (e.g. "Send 1–500 IDs" forDELETE /ns/{namespace}/memories, "up to 50" profile buckets, "five nested levels and 200 operands per logical group" for filters). No/v5/api-reference/overviewor/v5/openapilink is asserted anywhere.Relationship to open work — read this first
This draft covers the same ground as #1691 by @sohamd22 (identical title; 24 files here vs 26 there), which is open, non-draft, and part of an active stacked PR set with #1692. It was produced independently, but it is not submitted for review: #1691 is the canonical work. It is kept as a draft with this disclosure posted on purpose.
For transparency about how this draft was built: its prose was compared sentence-by-sentence against the in-review migration-guide branch and rewritten until no contiguous two-sentence overlap remained (remaining identity is limited to endpoint paths, JSON examples, and other fact strings). Anything here that is useful should be folded into #1691 as review input rather than merged as a duplicate.
Validation
Structure verified:
docs.jsonparses, all nav entries and all snippet imports resolve, frontmatter valid on all 23 new pages, code fences balanced,git diff --checkclean, single commit authored asAswin-Ram-K. Ten-plus factual claims re-checked against in-repo schemas; the three schema names cited in the filters warning were independently line-verified. Independently re-validated by three separate models before this draft was finalised.