docs: unified is the only schema; hide the knowledge and memory docs (PRO-1618), stacked on #298

[SohamRatnaparkhi]

Stacked on #298 (soham/pro-1618-unified-contract). Knowledge and memory (split databases) are deprecated, so unified is now the only schema a reader sees. Hidden pages are not deleted: they stay reachable by URL, carry noindex: true, and open with one <Warning> line saying they are deprecated and pointing to Ingest context and Query.

Hidden (out of docs.json, noindex: true, one-line deprecation warning)

The whole v1 version (52 pages). v1 is the knowledge, memories and recall API, so every v1 page documents the old schema:

• Get started: get-started/introduction, get-started/core-concepts, get-started/quickstart
• Essentials: essentials/architecture, memories, knowledge, app-sources, recall, webhooks, multi-tenant, metadata, context-graphs, api-results, semantic-search
• Cookbooks: cookbooks/index and the 12 v1 cookbooks
• API reference: api-reference/index, sdks, error-responses, and every api-reference/endpoint/* page (tenants, ingestion, memories, upload-knowledge, add-memory, verify-processing, delete-memory, delete-knowledge, recall overview / full / preferences / boolean, list overview / data, fetch-content, graph-relations)

v2 split pages: essentials/v2/split-databases (removed from Concepts), plus essentials/v2/knowledge, essentials/v2/memories and essentials/v2/app-sources, which were already out of the navigation.

v2 Cookbooks tab (13 pages): every cookbook ingests with type: "memory" / memories / app_knowledge and reads chunk_content / graph_context, so the tab is gone until they are rewritten.

The v1 plugin and AGENTS entries were shared with v2 and stay visible there. continuity-assurance was only in the v1 nav and is not about the schema, so it moves to v2 Concepts. essentials/v2/bring-your-own-graph is rewritten to the current contract (keyed by context_id) and joins Concepts.

The single deprecation note

essentials/v2/databases-and-collections.mdx, at the top: knowledge and memory (split databases) are deprecated, unified is the way to go, and you pass nothing to get it. No page documents type (or type: "unified") as a request field.

Links repointed or removed

Links and cards on visible pages that pointed at hidden pages:

• snippets/legacy-line.mdx (the "see Split databases" line on Query, Ingest, Context graphs, How to Use API Results, the Query and Ingest Context endpoint pages): removed, with the snippet.
• Split databases links on Query, Query reference, Query overview, Ingest, API results, Context graphs, Glossary, API reference index, Sources overview, Ingest Context: removed with their sections.
• Knowledge / Memories / App sources links on Architecture, Databases and collections, Access control, Connectors, BYOG, Attributes, SDKs, Sources overview, Context status: repointed to Ingest context, Connectors or Databases and collections, or dropped.
• /cookbooks/v2/index on Introduction and Quickstart: removed.
• /essentials/memories and /essentials/knowledge on the Claude Code plugin page: removed with the searchMode / ingestionMode sections.
• /get-started/core-concepts (v1) on Architecture: repointed to /get-started/v2/core-concepts.

Visible pages that stopped teaching the split schema

• Query contract (Query, Query reference, Query overview, API results, Context graphs): data is exactly chunks, graph, forceful_relations, llm_prompt. Relations gain optional timestamp (epoch seconds, a float); temporal_details is omitted when empty; the graph is deduplicated across both lanes and not capped; forceful relations are followed only in thinking mode. Every llm_prompt example drops query path, / chunk relation, : a ranked fact reads - [P1] **A** -pred→ **B** (relevance 0.81) [1], an unranked one has no parenthetical. Split sections, type warnings, "parse by shape", chunk_id_to_group_ids and build_string mentions are gone.
• AGENTS.mdx: rewritten to the current contract (context items, four-key response, llm_prompt, attributes, list / inspect / relations / delete without type).
• Attributes: teaches attributes / custom_attributes on items and the $ operator filter (checked against service/attributes_filter.go); the metadata / metadata_filters / app_knowledge body is gone.
• API reference: SDKs, index, error responses, Ingest Context (split section removed), Sources overview, List / Delete / Relations / Subgraph / Inspect / Status / Stats / Database status / Create / List databases / delete pages. List Context, Delete Context, Context Relations, Connected Subgraph, Database Stats, Database Status, Create Database and List Databases are unbound from OpenAPI (the published spec still renders the knowledge / memory type selector for those operations, same precedent as docs: unified ingest and query contract (PRO-1618), stacked on #296 #298's cc23a90) and document their parameters and responses by hand.
• Plugins (Claude Code, MCP, CLI, OpenClaw): the knowledge / memory knobs (kind, --kind, searchMode, ingestionMode) and old endpoints are gone; each page describes what the plugin sends and reads on a current database, checked against the plugin branches.
• Essentials and get started: Ingest (before/now split table and split accordions removed), Databases and collections, Architecture, Connectors, Webhooks, Access control, Glossary, Semantic search, Introduction, Core concepts, Quickstart.

Corrections found against the application code

• The ingest 202 result key is results[].id, not results[].source_id (domain/memories/v2_ingest.go).
• GET /context/inspect returns stored content only (domain/fetch/v2.go), so title, timestamp and attributes now come from POST /context/list with ids.
• Empty query is 400 INVALID_INPUT; a malformed attributes filter is 400 VALIDATION_ERROR.

Left in place on purpose

• metadata_filters stays on Connectors (and one neutral row on the Query reference): it is the only way to scope a query to connector fields under additional_metadata, which attributes does not reach.
• Wire names that are historical but real: vectorstore_status.knowledge / .memories, knowledge_collection / memory_collection (both report the one collection), the sources key on List Context, results[].infer, and database_metadata / additional_metadata on PATCH /context/{id}/metadata.

Second pass: what a new user meets

Context categories: hidden, not deprecated

• essentials/v2/context-categories leaves the navigation (Build), gets noindex: true and is listed in mintlify-hygiene.toml excludes. It has no deprecation warning: it is not promoted yet, not deprecated. No visible page links to it.
• context_category is no longer shown as something to set: removed from the Ingest guide (section 7, the field row, the misspelling accordion and the examples; later sections renumbered and every inbound anchor repointed), Core concepts, Quickstart, Databases and collections, AGENTS.mdx, SDKs, the API reference index, Sources overview, Ingest Context (examples and field row), Error responses, and the MCP and CLI plugin pages.
• enrichment_kind stays in the chunk field reference (it is in the response contract), described the same way on Query, the Query reference and AGENTS.mdx: "an optional label; omitted when none was set". Example responses no longer show it and example llm_prompts no longer print a **Category:**, since no example request sets one. The llm_prompt sections table still says a result line can carry **Category:** (the server prints it only when set).
• The example llm_prompt on Query, the Query reference and API results now echoes the example request's query instead of a different one.

Split databases

Already hidden by the first pass; re-checked: not in docs.json, no link, card or "see also" from any visible page.

New-user path

• Sidebar: Get started reads Introduction, Quickstart, Core concepts (the order the Introduction's own steps give). Build opens with Databases and collections (the one deprecation note, and where data goes), then Ingest, Query, How to Use API Results, then Attributes, Connectors, Access control, Webhooks. The Cypher graph collections page gets its own sidebarTitle, so the sidebar no longer shows two "Bring Your Own Graph" entries, and the ingest-time BYOG page points to it.
• Core concepts: the "three kinds" of context are described as kinds of content, not a setting.
• Quickstart: it ingests one call per collection, not "in one call".
• Databases and collections: shared context goes in a shared collection such as company (what its own examples query), or the default collection.
• Forceful relations are followed only in thinking mode: Ingest, Glossary, Ingest Context and AGENTS.mdx now say so, as Query already did.
• Ingest: an unknown item field is ignored without an error (it said "refused or dropped"; the server has no strict decoder), and the SDK note says enrich / instructions are set per item, matching Ingest Context.
• Architecture: the status error field is error_message.
• Update Source Metadata and the API reference index: database_metadata / additional_metadata are this endpoint's names for an item's attributes / custom_attributes; the ingest names are not read there. The index's inspect row says what inspect is for.

OpenAPI spec: no change from this stack

api-reference/v2/openapi.json is restored to main's version, so the stack as a whole makes no spec change (the spec arrives through the auto-generated spec PR). All 27 visible pages bound with openapi: frontmatter name an operation that main's spec has (webhooks, connectors, feedback, GET /context/status, GET /context/inspect, PATCH /context/{id}/metadata, GET and DELETE /databases/collections, DELETE /databases, PATCH /databases/{database}/metadata-schema). git diff origin/main -- api-reference/v2/openapi.json is empty at this head. Pages that need operations only the newer spec has (Connected Subgraph and the others listed above) are hand-written and not bound.

Checks

• npx mint@latest validate: build validation passed.
• npx mint@latest broken-links: no broken links.
• mintlify-hygiene check and check --deny-warnings (v0.3.0 darwin binary): clean. The hidden pages, including Context categories, are listed in mintlify-hygiene.toml excludes.
• python3 scripts/verify_agents_endpoints.py: 35 endpoint mentions; the one miss is GET /context/subgraph, which is live but only in the newer spec (now main's spec is kept). It resolves when the auto-generated spec lands. The script is not in CI.
• docs.json is valid JSON and every page it lists exists; no visible page links to a hidden page (checked with a script over every nav page, including heading anchors); no em or en dashes on added lines.

🤖 Generated with Claude Code

[openhack-agent]

OpenHack Summary

Security review of docs: unified is the only schema; hide the knowledge and memory docs (PRO-1618), stacked on #298. 116 changed files; 0 findings at or above the low reporting threshold.

0   0   0   0

Confidence Score: 5/5

No reportable security findings were detected in this scan.

Security merge-readiness rubric: 1 = critical, 2 = high, 3 = medium, 4 = low, 5 = no reportable findings. This score reflects scan findings, not a guarantee of correctness or complete coverage.

Files Needing Attention: None

Important Files Changed

• AGENTS.mdx (modified)
• api-reference/endpoint/add-memory.mdx (modified)
• api-reference/endpoint/boolean-recall.mdx (modified)
• api-reference/endpoint/create-tenant.mdx (modified)
• api-reference/endpoint/delete-knowledge.mdx (modified)
• api-reference/endpoint/delete-memory.mdx (modified)
• api-reference/endpoint/delete-tenant.mdx (modified)
• api-reference/endpoint/fetch-content.mdx (modified)
• api-reference/endpoint/full-recall.mdx (modified)
• api-reference/endpoint/graph-relations.mdx (modified)
• api-reference/endpoint/infra-status.mdx (modified)
• api-reference/endpoint/ingestion-overview.mdx (modified)
• api-reference/endpoint/list-data.mdx (modified)
• api-reference/endpoint/list-overview.mdx (modified)
• api-reference/endpoint/list-sub-tenant-ids.mdx (modified)
• api-reference/endpoint/list-tenant-ids.mdx (modified)
• api-reference/endpoint/memories-overview.mdx (modified)
• api-reference/endpoint/monitor-tenant.mdx (modified)
• api-reference/endpoint/recall-overview.mdx (modified)
• api-reference/endpoint/recall-preferences.mdx (modified)
• api-reference/endpoint/tenants-overview.mdx (modified)
• api-reference/endpoint/upload-knowledge.mdx (modified)
• api-reference/endpoint/verify-processing.mdx (modified)
• api-reference/error-responses.mdx (modified)
• api-reference/index.mdx (modified)

View all 116 changed files

Last reviewed commit: ca2ac19 · View review on OpenHack

---

TIP: Mention @openhack-agent in a PR comment to request a review or ask a question. Use @openhack-agent fix all for every finding, or @openhack-agent fix unresolved threads for open review threads only.

[openhack-agent]

OpenHack reviewed this commit. See the OpenHack Summary for the confidence score and fix actions.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no new changes exist since the previous review, all prior findings are resolved or withdrawn, and no applicable repository-rule violations remain.

Summary

This documentation overhaul presents unified context as HydraDB’s sole public schema while retaining deprecated split-schema pages at their existing URLs with noindex notices.

• Removes v1, split-database, legacy cookbook, and context-category pages from navigation.
• Rewrites onboarding, ingestion, querying, SDK, plugin, graph, attribute, and API-reference guidance around the unified contract.
• Aligns query responses around chunks, graph, forceful_relations, and llm_prompt.
• Restores the OpenAPI document to the version currently published from main; newer operations are documented manually where needed.
• Repoints visible links away from hidden legacy content and adds hygiene exclusions for intentionally hidden pages.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Introduction] --> B[Quickstart]
    B --> C[Core concepts]
    C --> D[Databases and collections]
    D --> E[Ingest unified context]
    E --> F[Query]
    F --> G[Use API results]
    G --> H[Attributes and integrations]

    I[Legacy v1 and split-schema pages] --> J[Hidden from navigation]
    J --> K[Existing URLs retained]
    K --> L[noindex and deprecation guidance]

Loading

_{Reviews (6) · Last reviewed commit: "docs: smooth the new-user path through G..."}

[github-actions]

✅ Mintlify Hygiene

No issues found.

[SohamRatnaparkhi]

@greptileai review