GeezerVison

Purpose of the change

Fewer top-level files for contributors to read (#1652). The repository root loses CONTRIBUTING-CORE.md, CONTRIBUTING-DOCS.md, STYLE_GUIDE.md, and AGENTS.md. CONTRIBUTING.md becomes the one contributing guide, and it links to the longer guides that already live in folders.

Stack

This PR's eleven commits, bfa1bab..d7afd15, are on main after #1869's merge (377510d).

Description

• CONTRIBUTING.md says once what the three contributing guides each repeated: the issue-first workflow, uv setup, the checks CI runs (Ruff, ty, and pytest), and the pull request steps. It links to docs/README.md for previewing the documentation site, to maintainers/running-unit-tests.md for selecting tests, and to the TypeScript client's README for its commands.

• The checks are CI's commands. From the repository root, pytest stops at a collection error, because integrations/strands-memmachine needs strands and no extra installs it. ty check packages reports two unresolved spacy imports from the optional multihop group. So the guide gives pytest the package test directories and type checks each package with --project, and the whole-suite and keyword commands in maintainers/running-unit-tests.md name the same directories. The keyword example's create_memory matched no test, so it now uses add_memory.

• Integration tests with a server of your own: most integration tests start their databases in Docker. The Checks section lists the rest and when each skips. The NebulaGraph tests (NEBULA_HOST, NEBULA_USER, NEBULA_PASSWORD) and the Python client's tests (MEMORY_BACKEND_URL) skip when their server can't be reached. The tests on an OpenAI-compatible server such as Ollama skip only when OLLAMA_HOST is unset, and expect a base URL such as http://localhost:11434/v1, not Ollama's own host:port form.

• Paid-API tests: the Checks section carries [contributor setup 1] Read paid-API test credentials from test-only variables #1869's text from CONTRIBUTING-CORE.md. It lists the MEMMACHINE_TEST_* variables and warns that the tests call the real APIs, billed to those keys.

• Dropped as stale or unverified: three steps from CONTRIBUTING-DOCS.md:

  • mint.json: the repository has docs/docs.json instead.
  • mintlify install: the current CLI's README lists no such command.
  • Pre-commit hooks: the repository has no hook configuration.

  docs/README.md links to Mintlify's installation guide for the current steps. Also dropped: the claim that unsigned commits fail GitHub Actions, since no workflow checks signatures. The signing requirement itself stays.

• Style: a Style section in CONTRIBUTING.md gives the rules Ruff and ty don't check: names, types, suppression comments, library use, comments and docstrings, factoring and caching, and test markers. It says existing code may not match them, which doesn't exempt new code.

• docs/README.md: Handoff files for Mintlify and Site skills #1706 added it so that anyone can get up to speed with documentation work. Most of it copied Mintlify's setup steps, and its Node requirement had drifted: it said 18 or higher, but the mint CLI refuses to start below 20.17 or on Node 25. It now links to Mintlify's installation guide, which states the current requirement and covers installing Node, and keeps only what this repository decides: run mint dev from docs/, and the checks docs CI runs there.

• STYLE_GUIDE.md: its Ruff and ty guidance is in the Checks section, and its Markdown rules named markdownlint, which nothing runs. The PR template's style checkbox now points at CONTRIBUTING.md, whose Style section replaces the file's principles, and the docs community page and .dockerignore drop their entries for the file.

• AGENTS.md: its commands repeat CONTRIBUTING.md and the TypeScript client's README. Of its conventions, Ruff and ty enforce the formatting, import, naming, and annotation rules. Its other preferences, such as pydantic models for structured data, small functions, pytest fixtures, and catching broad exceptions only at API boundaries, are not carried over.

Fixes/Closes

Part of #1652. Two items stay open:

• USAGE.md: [Docs]: Too many top-level repo files #1652's fix for it is a recommended usage path simple enough to fit in the README, which is a product change (related: memmachine-configure installs a JDK and Neo4j from downloaded archives #1866).
• alembic.ini: [Docs]: Too many top-level repo files #1652 defers it to Schema provisioning runs from every process's boot path: create_all races on cold boot and never evolves a table, Alembic runs destructive migrations on first use #1570, and [schema migration 1/2] Add memmachine-server migrate, which creates every configured store's schema before servers start #1825 gives it one section per store lineage.

Type of change

• Documentation update

How Has This Been Tested?

• Manual verification

• At d7afd15, after the second review: the two new commits change only the integration-test bullets in CONTRIBUTING.md and the commands in maintainers/running-unit-tests.md, which now all use uv run pytest. Two of them, the test_chunk_text and -k add_memory commands, pass as written (1 and 11 passed).

• At 4695aff: the new commit changes only docs/README.md and one line of CONTRIBUTING.md. The README's three links return 200, and its commands are the ones docs-checks.yml runs in docs/. The Node bounds come from the CLI's own startup check (@mintlify/cli 4.0.1789, bin/helpers.js), and Mintlify's installation guide states v20.17.0 or newer.

• At 29c2d40, rebased onto main after [contributor setup 1] Read paid-API test credentials from test-only variables #1869 merged: the PR's diff is identical to the previous head's (git diff 862a08309 774946d01 equals git diff 377510d43 29c2d4001), because main has changed none of the files this PR touches. git grep still finds no reference to the removed files.

• At 774946d, after review: the five new commits change only CONTRIBUTING.md and maintainers/running-unit-tests.md. uv run pytest -k add_memory packages/server/server_tests packages/client/client_tests passes (11 passed). The integration-test variables, defaults, and skip conditions match the NebulaGraph, Ollama, and client test fixtures.

• At 797dce5, rebased onto [contributor setup 1] Read paid-API test credentials from test-only variables #1869: the code is identical to [contributor setup 1] Read paid-API test credentials from test-only variables #1869's (git diff 862a08309 797dce5f9 -- packages .github/workflows is empty), so [contributor setup 1] Read paid-API test credentials from test-only variables #1869's checks cover it. Its documentation differs from the previous head, 4a95f4a, only in the integration-test paragraph.

• At d5a39a8, the previous base, after uv sync --all-extras: ruff format --check, ruff check, and the three ty check --project commands pass, and uv run pytest packages/server/server_tests packages/client/client_tests passes (2386 passed, 3 skipped).

• Every relative link and anchor in CONTRIBUTING.md resolves, and its external links return 200.

• git grep finds no reference to the removed files.

Test Results: as listed above.

Checklist

• I have signed the commit(s) within this pull request
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation

Further comments

Adding testpaths to pytest's configuration would make a plain uv run pytest work from the root again. That is a configuration change, so it is not in this PR.

🤖 Written by Claude Code (Claude Opus 5.5) on behalf of @edwinyyyu.