docs: migrate to MkDocs Material with Diátaxis-inspired IA#295
Open
nkanu17 wants to merge 5 commits into
Open
Conversation
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures the project documentation into a Diátaxis-inspired information architecture and migrates the docs build to MkDocs Material (with additional plugins for API refs, notebook rendering, and AI-agent-friendly exports).
Changes:
- Replaces the previous flat docs structure with Concepts / User Guide / Examples / API Reference sections and updated navigation.
- Switches the docs toolchain to MkDocs Material + plugins (mkdocstrings, mkdocs-jupyter, llms.txt generation) and updates the CI docs workflow to build strictly via
uv. - Adds new/expanded docs content (e.g., macOS no-Docker setup, memory editing how-to, auto-generated server package reference pages).
Reviewed changes
Copilot reviewed 72 out of 84 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| SKILL.md | Adds an agent “skill” file (currently still template placeholders). |
| README.md | Updates project title/tagline (docs links still point to old site). |
| pyproject.toml | Updates docs dependency group for MkDocs Material + plugins. |
| mkdocs.yml | New Material theme config, plugins, and full multi-section nav. |
| .github/workflows/docs.yml | Migrates docs CI to Python 3.12 + uv run mkdocs build --strict. |
| examples/agent_memory_server_interactive_guide.ipynb | Expands notebook intro/structure text for the interactive guide. |
| docs/index.md | New landing page with hero + section entry cards. |
| docs/user_guide/index.md | New User Guide landing page with tutorial cards. |
| docs/user_guide/01_quick_start.md | Updates Quick Start copy/links and includes a Docker Compose production example snippet. |
| docs/user_guide/02_installation.md | Updates installation guide links for new structure. |
| docs/user_guide/03_no_docker_setup.md | Adds native macOS (no Docker) setup path. |
| docs/user_guide/how_to_guides/index.md | Adds How-To hub page with card grid + quick reference table. |
| docs/user_guide/how_to_guides/configuration.md | Updates wording and internal links for new structure. |
| docs/user_guide/how_to_guides/authentication.md | Updates wording for renamed product and structure. |
| docs/user_guide/how_to_guides/security.md | Converts admonitions/formatting and updates links (contains MyST-style admonitions). |
| docs/user_guide/how_to_guides/llm_providers.md | Updates links/wording; Bedrock sections and cross-links. |
| docs/user_guide/how_to_guides/embedding_providers.md | Updates wording for renamed product. |
| docs/user_guide/how_to_guides/aws_bedrock.md | Updates wording/links and formatting for Bedrock guide. |
| docs/user_guide/how_to_guides/advanced_vector_db.md | Updates wording for renamed product. |
| docs/user_guide/how_to_guides/custom_vector_db.md | Adds custom vector DB factory how-to page. |
| docs/user_guide/how_to_guides/query_optimization.md | Fixes wording and updates internal link. |
| docs/user_guide/how_to_guides/integration_patterns.md | Updates wording and points extraction link to Concepts. |
| docs/user_guide/how_to_guides/development.md | Fixes list formatting in release instructions. |
| docs/examples/index.md | Adds Examples landing page with cards. |
| docs/examples/use_cases.md | Updates wording for renamed product. |
| docs/examples/agent_examples.md | Adds agent examples hub page linking to per-agent docs pages. |
| docs/examples/travel_agent.md | Adds Travel Agent example page. |
| docs/examples/memory_prompt_agent.md | Adds Memory Prompt Agent example page. |
| docs/examples/memory_editing_agent.md | Adds Memory Editing Agent example page. |
| docs/examples/ai_tutor.md | Adds AI Tutor example page. |
| docs/examples/recent_messages_limit_demo.md | Adds Recent Messages Limit demo page (snippet currently mismatches described parameter). |
| docs/examples/langchain.md | Updates links to new API/User Guide structure. |
| docs/api/index.md | Adds API Reference landing page with interface/SDK cards and matrix. |
| docs/api/cli.md | Updates CLI docs formatting (contains MyST-style admonition). |
| docs/api/mcp.md | Fixes list indentation for MCP notes. |
| docs/api/java_sdk.md | Adds Java SDK documentation page. |
| docs/api/typescript_sdk.md | Adds TypeScript SDK documentation page. |
| docs/api/server/index.md | Adds mkdocstrings-driven server package reference landing page. |
| docs/api/server/models.md | Adds mkdocstrings page for agent_memory_server.models. |
| docs/api/server/working_memory.md | Adds mkdocstrings page for agent_memory_server.working_memory. |
| docs/api/server/long_term_memory.md | Adds mkdocstrings page for agent_memory_server.long_term_memory. |
| docs/api/server/memory_strategies.md | Adds mkdocstrings page for agent_memory_server.memory_strategies. |
| docs/api/server/memory_vector_db.md | Adds mkdocstrings page for agent_memory_server.memory_vector_db. |
| docs/api/server/extraction.md | Adds mkdocstrings page for agent_memory_server.extraction. |
| docs/api/server/summarization.md | Adds mkdocstrings page for agent_memory_server.summarization. |
| docs/api/server/filters.md | Adds mkdocstrings page for agent_memory_server.filters. |
| docs/api/server/auth.md | Adds mkdocstrings page for agent_memory_server.auth. |
| docs/api/server/config.md | Adds mkdocstrings page for agent_memory_server.config. |
| docs/api/server/llm.md | Adds mkdocstrings page for agent_memory_server.llm. |
| docs/concepts/index.md | Adds Concepts landing page with cards and “where to start” guidance. |
| docs/concepts/working_memory.md | Updates wording, formatting, and links to new structure. |
| docs/concepts/long_term_memory.md | Updates wording/links (contains MyST-style admonition). |
| docs/concepts/memory_lifecycle.md | Replaces in-page memory editing section with link to dedicated how-to. |
| docs/concepts/memory_extraction.md | Updates links/formatting (contains MyST-style admonitions). |
| docs/concepts/contextual_grounding.md | Updates LLM providers link location. |
| docs/concepts/summary_views.md | Updates related links to new structure. |
| docs/concepts/recency_boost.md | Adds new Recency Boost concept page. |
| docs/for-ais-only/index.md | Adds AI-agent internal docs landing page. |
| docs/for-ais-only/REPOSITORY_MAP.md | Adds module map + conventions for agents modifying code. |
| docs/for-ais-only/FAILURE_MODES.md | Adds “intentional behaviors” reference for agents. |
| docs/for-ais-only/BUILD_AND_TEST.md | Adds build/test guide (currently describes Sphinx, not MkDocs). |
| docs/stylesheets/extra.css | Adds layout tweaks and mkdocs-jupyter rendering improvements. |
| docs/stylesheets/redis-brand.css | Adds Redis brand tokens/Material overrides (header comment mentions wrong site). |
| docs/stylesheets/redis-ai-hub-header.css | Adds shared “Redis AI Hub” header styles (appears standalone). |
| docs/javascripts/redis-ai-hub-header.js | Adds shared “Redis AI Hub” header injector JS (appears standalone). |
| docs/assets/redis-logo-script.svg | Adds Redis script logo asset. |
| docs/assets/redis-logo-script-red.svg | Adds red variant Redis script logo asset. |
| docs/assets/redis-ai-hub/redis-ai-hub-header.js | Adds alternate shared hub header injector JS. |
| docs/assets/redis-ai-hub/redis-ai-hub-header.css | Adds alternate shared hub header styles. |
| docs/assets/redis-ai-hub/redis-ai-hub-config.js | Adds per-library hub header config. |
| docs/README.md | Removes legacy docs README landing page. |
| docs/getting-started-index.md | Removes legacy Getting Started index page. |
| docs/developer-guide-index.md | Removes legacy Developer Guide index page. |
| docs/operations-guide-index.md | Removes legacy Operations Guide index page. |
| docs/advanced-topics-index.md | Removes legacy Advanced Topics index page. |
| docs/api-reference-index.md | Removes legacy API Reference index page. |
| docs/python-sdk-index.md | Removes legacy Python SDK index page. |
| docs/agent-examples.md | Removes legacy agent examples mega-page (replaced by new Examples section). |
Comments suppressed due to low confidence (10)
docs/user_guide/how_to_guides/security.md:7
- MkDocs Material doesn’t support MyST-style fenced admonitions like
{danger} ...with the currentmkdocs.ymlmarkdown extensions. This will render as a code block (and may fail strict builds). Convert this to Material’s!!! dangeradmonition syntax (or add the required Markdown extension/plugin that supports directive-style admonitions).
docs/user_guide/how_to_guides/security.md:124 - This MyST-style fenced admonition (
{tip} ...) is not supported by the configured MkDocs Markdown extensions, so it will render incorrectly. Use Material’s!!! tipsyntax (or enable an extension that supports directive-style admonitions).
docs/user_guide/how_to_guides/security.md:230 - This MyST-style fenced admonition (
{tip} ...) is not supported by the configured MkDocs Markdown extensions. Convert it to Material’s!!! tipsyntax (or enable an extension that supports directive-style admonitions).
docs/user_guide/how_to_guides/security.md:328 - This MyST-style fenced admonition (
{warning} ...) is not supported by the configured MkDocs Markdown extensions. Convert it to Material’s!!! warningsyntax (or enable an extension that supports directive-style admonitions).
docs/concepts/memory_extraction.md:128 - MkDocs Material won’t render MyST-style fenced admonitions like
{danger} ...with the currentmkdocs.ymlconfiguration, so this will show up as a code block (and can break strict builds). Convert to!!! danger(or enable an extension that supports directive-style admonitions).
docs/concepts/memory_extraction.md:215 - MkDocs Material won’t render MyST-style fenced admonitions like
{note} ...with the currentmkdocs.ymlconfiguration. Use!!! noteadmonitions (or enable an extension that supports directive-style admonitions) so this callout renders correctly.
docs/concepts/memory_extraction.md:318 - MkDocs Material won’t render MyST-style fenced admonitions like
{tip} ...with the currentmkdocs.ymlconfiguration. Convert to Material’s!!! tipsyntax (or enable directive-style admonitions) to avoid broken rendering.
docs/concepts/long_term_memory.md:232 - This MyST-style fenced admonition (
{note} ...) isn’t supported by the configured MkDocs Markdown extensions, so it will render as a code block. Convert it to Material’s!!! notesyntax (or add the needed extension/plugin).
docs/api/cli.md:51 - This MyST-style fenced admonition (
{warning} ...) isn’t supported by the configured MkDocs Markdown extensions, so it won’t render as an admonition. Convert to Material’s!!! warningsyntax (or enable directive-style admonitions).
docs/user_guide/01_quick_start.md:450 - The Docker Compose YAML example’s list indentation is inconsistent (e.g., list items under
ports:,volumes:,environment:,depends_on:are indented one space too little), making the snippet invalid YAML when copied. Align list items so they are properly nested under their keys.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+4
to
+32
| description: | | ||
| (Redis Agent Memory Server.) | ||
| Use this skill whenever the user asks to (list 3-5 concrete triggers). | ||
| runtime: | ||
| language: python | ||
| package: agent_memory_server | ||
| install: "pip install agent_memory_server" | ||
| links: | ||
| docs: https://ai.redis.io/agent-memory/ | ||
| llms_txt: https://ai.redis.io/agent-memory/llms.txt | ||
| llms_full_txt: https://ai.redis.io/agent-memory/llms-full.txt | ||
| repository: https://github.com/redis/agent-memory-server | ||
| --- | ||
|
|
||
| # Agent Memory Agent Skill | ||
|
|
||
| ## When to use | ||
|
|
||
| - (List 3-5 trigger phrases / situations. Be specific about what this | ||
| library does that no other portfolio repo does.) | ||
|
|
||
| Do **not** use this skill for (...). Fall back to {{ALTERNATIVE_LIBRARY}} | ||
| for those cases. | ||
|
|
||
| ## Minimal install | ||
|
|
||
| ```bash | ||
| pip install "agent_memory_server>=...,<..." | ||
| ``` |
Comment on lines
4
to
8
| # Agent Memory Server | ||
|
|
||
| A memory layer for AI agents. | ||
| Session Memory and Long-Term Memory for AI Agents. | ||
|
|
||
| **[Documentation](https://redis.github.io/agent-memory-server/)** • **[GitHub](https://github.com/redis/agent-memory-server)** • **[Docker](https://hub.docker.com/r/redislabs/agent-memory-server)** |
Comment on lines
+36
to
+62
| ## Building the docs | ||
|
|
||
| The docs are Sphinx (MyST + autodoc). Notebooks render via `myst-nb`. | ||
|
|
||
| ``` | ||
| uv sync --group docs # if a docs group is defined; otherwise: | ||
| pip install -r docs/requirements.txt | ||
| sphinx-build -b html docs docs/_build/html | ||
| open docs/_build/html/index.html | ||
| ``` | ||
|
|
||
| The Sphinx build should complete with zero warnings. Treat any warning as a | ||
| breaking change. To enforce this in CI: | ||
|
|
||
| ``` | ||
| sphinx-build -W -b html docs docs/_build/html | ||
| ``` | ||
|
|
||
| The API reference under `docs/api/server/` is auto-generated by | ||
| `sphinx.ext.autosummary`; the package is mocked in `conf.py`'s | ||
| `autodoc_mock_imports` so the build does not require runtime deps. | ||
|
|
||
| ## CI gates | ||
|
|
||
| - `make verify` (pre-commit + API tests) on every PR. | ||
| - `sphinx-build -W` on every PR. | ||
|
|
Comment on lines
+27
to
+38
| ```python | ||
| from agent_memory_client import create_memory_client | ||
|
|
||
| client = await create_memory_client(base_url="http://localhost:8000") | ||
|
|
||
| # Get only the 3 most recent messages | ||
| _created, memory = await client.get_or_create_working_memory( | ||
| session_id="my-session", | ||
| namespace="demo", | ||
| context_window_max=3 | ||
| ) | ||
| ``` |
Comment on lines
+1
to
+5
| /* Redis brand tokens and Material theme overrides for sql-redis docs. | ||
| * Mirrors the redis-docs tailwind palette (Redis red #FF4438, Redis ink | ||
| * #091A23) and self-hosts the Space Grotesk + Space Mono pairing used on | ||
| * redis.io. | ||
| */ |
Replace the flat docs structure with a four-section, learning-flow information architecture (Concepts / User Guide / Examples / API Reference), powered by MkDocs Material with mkdocstrings, mkdocs-jupyter, and mkdocs-llmstxt. Highlights: - New section landing pages with card grids and cross-links - Notebook (examples/agent_memory_server_interactive_guide.ipynb) rendered as a docs page via mkdocs-jupyter - Shared Redis brand CSS (palette + Space Grotesk/Mono fonts) - Flush-sidebar layout (max-width: none) so nav and TOC pin to the viewport edges on wide screens - New AI-only docs section (REPOSITORY_MAP, BUILD_AND_TEST, FAILURE_MODES) for downstream agent ingestion - New how-to: memory editing - New per-example pages split out from the old aggregate agent-examples.md - Strict mkdocs build wired into CI (.github/workflows/docs.yml) - README + SKILL.md updated to point at the new structure No code logic changes outside docs and config.
nkanu17
added a commit
to nkanu17/agent-memory-server
that referenced
this pull request
May 11, 2026
- Convert MyST directive admonitions (```{warning} / {tip} / {note} /
{danger}```) to MkDocs Material's `!!! …` syntax in cli.md,
long_term_memory.md, memory_extraction.md (3x), and security.md (4x).
The MyST syntax was rendering as raw code blocks under our
pymdownx.admonition extension.
- Fix recent_messages_limit_demo.md snippet to actually use
`recent_messages_limit` via httpx (matching examples/recent_messages_limit_demo.py)
instead of the unrelated `context_window_max` parameter.
- Normalize Docker Compose YAML indentation in 01_quick_start.md from 5
to 6 spaces under nested keys, matching the project's own
docker-compose.yml convention.
- Update BUILD_AND_TEST.md to describe the MkDocs build (uv run mkdocs
build --strict) instead of the stale Sphinx commands.
- Update all 14 README.md documentation links from
redis.github.io/agent-memory-server/* (old GitHub Pages site) to
ai.redis.io/agent-memory/* (the site_url set in mkdocs.yml), with
per-link path remap for the new section structure.
- Fix redis-brand.css header comment (was 'sql-redis docs', now
'agent-memory-server docs') — leftover from cross-repo file copy.
- Remove SKILL.md template scaffolding that shipped unfilled with
placeholders like {{ALTERNATIVE_LIBRARY}} and 'list 3-5 trigger
phrases'.
- Convert MyST directive admonitions (```{warning} / {tip} / {note} /
{danger}```) to MkDocs Material's `!!! …` syntax in cli.md,
long_term_memory.md, memory_extraction.md (3x), and security.md (4x).
The MyST syntax was rendering as raw code blocks under our
pymdownx.admonition extension.
- Fix recent_messages_limit_demo.md snippet to actually use
`recent_messages_limit` via httpx (matching examples/recent_messages_limit_demo.py)
instead of the unrelated `context_window_max` parameter.
- Normalize Docker Compose YAML indentation in 01_quick_start.md from 5
to 6 spaces under nested keys, matching the project's own
docker-compose.yml convention.
- Update BUILD_AND_TEST.md to describe the MkDocs build (uv run mkdocs
build --strict) instead of the stale Sphinx commands.
- Update all 14 README.md documentation links from
redis.github.io/agent-memory-server/* (old GitHub Pages site) to
ai.redis.io/agent-memory/* (the site_url set in mkdocs.yml), with
per-link path remap for the new section structure.
- Fix redis-brand.css header comment (was 'sql-redis docs', now
'agent-memory-server docs') — leftover from cross-repo file copy.
- Remove SKILL.md template scaffolding that shipped unfilled with
placeholders like {{ALTERNATIVE_LIBRARY}} and 'list 3-5 trigger
phrases'.
| ${dropdown('Integrations', LIBRARIES.integration)} | ||
| </nav> | ||
| <div class="rah-actions"> | ||
| <button class="rah-search" onclick="alert('Federated search panel — not wired in prototype')">⌘K Search</button> |
There was a problem hiding this comment.
Prototype alert dialogs in committed JavaScript files
Low Severity
Both hub header JS files include a search button with onclick="alert('Federated search panel — not wired in prototype')". While these files aren't currently referenced in mkdocs.yml, if they're ever wired in (or consumed by another docs site as the comments suggest), users will see a raw browser alert() dialog when clicking the search button. This is prototype scaffolding that shouldn't ship.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit 4805f55. Configure here.
Restructure docs/api/cli.md so each command follows a consistent template: short description, Syntax block, Options/Arguments tables, and Examples. This mirrors the layout used in redis-vl-python's CLI reference and replaces the previous bullet-list option descriptions. - Add a top-level Installation, Getting help, and Commands overview section with a table linking to every command. - Convert every command (api, mcp, task-worker, schedule-task, rebuild_index, migrate-memories, migrate-working-memory) and every token subcommand (add, list, show, remove) to the new template. - Promote token from H3+H4 to H2+H3 so subcommands are first-class navigation entries, with a subcommand index table at the top. - Move the trailing Getting Help section into the Installation block (single source of truth) and convert security notes to a !!! warning admonition.
The page's right-hand TOC and the left-hand sidebar already provide a navigable command index; the duplicate top-of-page table added noise without adding information.
…ng autofixes - check-yaml: pass --unsafe so it can parse mkdocs.yml's '!!python/name:material.extensions.emoji.twemoji' tag (used by the pymdownx.emoji extension config). Without this flag the hook fails with 'could not determine a constructor for the tag …'. - Apply trailing-whitespace fixes to two SVG assets and end-of-file fix to redis-ai-hub-header.css produced by the same hooks.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
There are 2 total unresolved issues (including 1 from previous review).
Reviewed by Cursor Bugbot for commit 305cbbe. Configure here.
| } else { | ||
| inject(); | ||
| } | ||
| })(); |
There was a problem hiding this comment.
Divergent duplicate header JS files with different categories
Low Severity
Two copies of the Redis AI Hub header injector script exist with divergent library category structures. docs/assets/redis-ai-hub/redis-ai-hub-header.js has categories core, integration, tool, content, while docs/javascripts/redis-ai-hub-header.js has core, experimental, integration with a different item arrangement. Neither file is wired into mkdocs.yml via extra_javascript, making both effectively dead code that ships in the docs output.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit 305cbbe. Configure here.
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
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.
Summary
Replaces the flat
docs/tree with a four-section, learning-flow IA powered by MkDocs Material:how_to_guides/cluster (configuration, auth, AWS Bedrock, embedding/LLM providers, vector DBs, query optimization, security, integration patterns, memory editing)mkdocstringsEvery section has an
index.mdwith a card grid and cross-links to neighboring sections. Diátaxis-inspired, but with deliberate cross-quadrant links so readers can flow between concept → guide → example.Stack additions
mkdocs-materialmkdocstrings[python]mkdocs-jupyterexamples/agent_memory_server_interactive_guide.ipynbas a docs pagemkdocs-llmstxtllms.txt/llms-full.txtfor AI-agent ingestionmkdocs-section-index,mkdocs-autorefsStrict build wired into
.github/workflows/docs.yml— zero warnings tolerated.Brand & layout
docs/stylesheets/redis-brand.css— Redis palette + Space Grotesk / Space Mono fonts (mirrorsredis-docs)max-width: noneat desktop breakpoint) so nav and TOC pin to the viewport edges on wide screensattr_listcards, admonitions for callouts, twemoji iconsNotable additions
docs/for-ais-only/—REPOSITORY_MAP.md,BUILD_AND_TEST.md,FAILURE_MODES.md, andAUTHORING_STANDARD.md(system prompt that codifies the docs philosophy — Diátaxis-inspired, learning-flow first) for downstream AI agentsdocs/user_guide/how_to_guides/memory_editing.md— new how-todocs/user_guide/03_no_docker_setup.md— macOS-friendly setup pathdocs/api/server/*.md— one page per server module under API Referencedocs/examples/so MkDocs can render it without duplicating sourceRenames (no content loss)
The bulk of the diff is
R(rename) operations migrating files into the new structure, e.g.:Every page that moved keeps its original code blocks and examples; the old flat-structure landing pages (
README.mdindocs/,*-index.md) were removed because they're replaced by the newdocs/<section>/index.mdfiles.What this PR does not touch
agent_memory_server/runtime codeHow to verify locally
Strict build:
The CI workflow runs the same strict build and fails on any warning.
Follow-ups (open questions, not in this PR)
mikefor per-release docs?Note
Medium Risk
Large-scale documentation restructure and new MkDocs build tooling may break navigation/links or CI docs deploy if misconfigured, but it does not touch runtime/server code.
Overview
Migrates documentation to a MkDocs Material site with a Diátaxis-inspired information architecture (new
Concepts,User Guide,Examples,API Reference, plusfor-ais-only), including new landing pages, reorganized/rewritten content, and updated cross-links.Adds auto-generated API reference pages for
agent_memory_serverviamkdocstrings, enables notebook rendering viamkdocs-jupyter, and introduces new branding/layout assets (Redis brand CSS, full-width sidebars, notebook cell separators) plus a Redis AI Hub header injector.Updates the docs CI workflow to Python 3.12 and uv (
uv sync --group docs,uv run mkdocs build --strict), and tweaks pre-commit YAML checking to run with--unsafe.Reviewed by Cursor Bugbot for commit 305cbbe. Bugbot is set up for automated code reviews on this repo. Configure here.