Skip to content

docs: make quick start prove first memory - #293

Merged
cyfyifanchen merged 5 commits into
mainfrom
codex/readme-quick-start-first-memory
Jun 17, 2026
Merged

cyfyifanchen merged 5 commits into
mainfrom
codex/readme-quick-start-first-memory

Conversation

@cyfyifanchen

@cyfyifanchen cyfyifanchen commented Jun 17, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Reworks the README Quick Start around a first-time developer path: prerequisites, install, configure, start, health check, first memory write, flush, and search.
  • Adds a root .env.example so source-checkout users can copy a visible config file with cp .env.example .env.
  • Keeps .env.example synchronized with the packaged src/everos/templates/env.template through scripts/check_docs.py.
  • Adds a GitHub-rendered success callout after the first memory search so new users get a clear “core loop completed” moment.
  • Moves Use Cases directly underneath Quick Start and adds a short bridge from the first successful EverOS moment into community and integration examples.
  • Cross-verifies the README Quick Start, QUICKSTART.md, and README.zh-CN.md against the current CLI/API contracts.
  • Corrects the internal quickstart search response shape to include unprocessed_messages, and clarifies that cascade indexing can catch up after the synchronous Markdown write.
  • Removes everos --help from the main success path to reduce friction.
  • Keeps multimodal ingestion and contributor setup after the core loop.
  • Mirrors the README Quick Start and Use Cases ordering in README.zh-CN.md, and updates QUICKSTART.md with the copy option.

Why

The previous Quick Start got users to a running server, but did not show the first successful product loop. A new developer now sees how to create config, write a memory, search it back, understand why that moment matters, and immediately discover what people are building with persistent memory.

Verification

  • uv run python <quickstart contract smoke>
    • checks README / QUICKSTART.md / README.zh-CN.md contain the documented install, config, server, add, flush, and search steps
    • validates .env.example equals the packaged src/everos/templates/env.template
    • validates everos init --to <tmp>/.env through the Typer CLI and confirms 0600 permissions
    • validates /health on create_app(lifespan_providers=[])
    • validates the documented add / flush / search payloads against the current request DTOs
    • validates the default /search response data arrays, including unprocessed_messages
  • Real uv run everos server start --env-file <tmp> --port <random> health smoke
  • git diff --check
  • make docs-check
  • uv run pytest tests/unit/test_memory/test_search/test_dto.py -v
  • make test (1211 passed, 1 skipped)

@cyfyifanchen
cyfyifanchen marked this pull request as ready for review June 17, 2026 05:14
@cyfyifanchen
cyfyifanchen merged commit 9c7c9d7 into main Jun 17, 2026
7 checks passed
@cyfyifanchen
cyfyifanchen deleted the codex/readme-quick-start-first-memory branch June 17, 2026 05:16
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.

1 participant