Skip to content

Refresh public documentation and benchmark setup docs - #16

Merged
SleepyLGod merged 2 commits into
mainfrom
codex/public-documentation
Oct 4, 2026
Merged

SleepyLGod merged 2 commits into
mainfrom
codex/public-documentation

Conversation

@SleepyLGod

@SleepyLGod SleepyLGod commented Oct 4, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Streamline the README with installation, a short memory example, benchmark commands, and an architecture illustration.
  • Consolidate operator, aggregation, architecture, and configuration references.
  • Document dataset preparation, explicit DeepSeek Flash selection, Neo4j setup, checkpoint recovery, and result inspection.
  • Keep the public documentation tree focused on usage guides.

Validation

  • 82 offline benchmark CLI and bundle tests passed.
  • Validated 9 CLI invocations, 7 Python code blocks, 14 shell blocks, and 38 relative links.
  • Executed the API declaration examples and the DataFrame example offline.
  • git diff --check passed.

Documentation and example configuration only; no runtime source or default behavior changes. No live model or Neo4j deployment was run.

Summary by CodeRabbit

  • Documentation
    • Reworked the README with current setup instructions, a memory example, benchmark guidance, and development checks.
    • Added architecture and configuration guides covering memory workflows, supported options, defaults, and backend requirements.
    • Updated operator and grouped-aggregation references to describe current APIs and behavior.
    • Reorganized benchmark instructions for LOCOMO, LongMemEval, and MemoryAgentBench, including setup, runs, checkpoints, and result inspection.
  • Configuration
    • Added example settings for Neo4j benchmark deployments, with credentials left blank by default.

Organize installation, API, architecture, and configuration guides around runnable examples.
Document benchmark preparation, model selection, Neo4j setup, and result inspection.
Include the README architecture illustration and keep local working notes outside the public documentation tree.

Signed-off-by: Von <haodong.lu.me@gmail.com>
Copilot AI balanced review requested due to automatic review settings October 4, 2026 09:05

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 4, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-04T09:13:35.227919Z ca23a40 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Oct 4, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 42 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 59e1e745-2dcc-4a24-b782-c83bedd8e23c
📥 Commits

Reviewing files that changed from the base of the PR and between ca23a40 and b9c9706.

📒 Files selected for processing (3)
  • .gitignore
  • docs/design/operator-api.md
  • tools/evaluation/README.md

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 2db2357e-be55-4da9-a8f3-3adf0f007e43
📥 Commits

Reviewing files that changed from the base of the PR and between 93d98d1 and ca23a40.

⛔ Files ignored due to path filters (2)
  • docs/assets/architecture/architecture.svg is excluded by !**/*.svg
  • docs/optimization/incremental-semantic-view-maintenance.pdf is excluded by !**/*.pdf
📒 Files selected for processing (18)
  • .env.example
  • .gitignore
  • README.md
  • docs/architecture.md
  • docs/assets/architecture/architecture.tex
  • docs/configuration.md
  • docs/design/TODO.md
  • docs/design/groupby-aggregation-api-rationale.md
  • docs/design/groupby_agg.md
  • docs/design/lotus-lowering.md
  • docs/design/operator-api.md
  • docs/design/policy-differentiation-dataflow-runtime.zh.md
  • docs/design/v0.0-interface.md
  • docs/design/window.en.md
  • docs/design/window.md
  • docs/optimization/incremental-semantic-view-maintenance.tex
  • docs/reference/rationale-df-mem-views.md
  • tools/evaluation/README.md
💤 Files with no reviewable changes (9)
  • docs/design/window.en.md
  • docs/design/groupby-aggregation-api-rationale.md
  • docs/design/policy-differentiation-dataflow-runtime.zh.md
  • docs/design/v0.0-interface.md
  • docs/design/TODO.md
  • docs/design/window.md
  • docs/optimization/incremental-semantic-view-maintenance.tex
  • docs/design/lotus-lowering.md
  • docs/reference/rationale-df-mem-views.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.


📝 Walkthrough

Walkthrough

The PR replaces project and benchmark guides, adds architecture and configuration references, and updates operator documentation. It adds Neo4j environment examples and ignore rules, and removes several older design and research documents.

Changes

Project documentation refresh

Layer / File(s) Summary
Setup and benchmark workflows
.env.example, README.md, tools/evaluation/README.md
The README and evaluation guide describe installation, credentials, memory usage, benchmark workflows, and development checks. .env.example adds Neo4j settings and identifies the LOTUS live-test opt-in.
Architecture overview
docs/architecture.md, docs/assets/architecture/architecture.tex
The architecture guide describes memory declarations, maintenance planning and execution, storage, retrieval, and checkpointing. A TikZ figure depicts the specification, compiler, plan, executor, and connected services.
Configuration reference
docs/configuration.md
The configuration guide documents credentials, LOTUS settings, benchmark options, batching and candidate-profile constraints, storage requirements, tracing, and checkpoint recovery limits.
Operator guides and design-document cleanup
docs/design/*, docs/optimization/*, docs/reference/*, .gitignore
The operator and grouped-aggregation guides describe current-checkout APIs and behavior. The PR removes older design and research documents and adds ignore rules for experiment artifacts and local documents.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to ca23a

The refreshed guides and setup examples have no established merge-blocking issue. The conflicting ignore rules concern a document that is not present in the repository.

Architecture Summary

Architecture risk: 🔵 Low · up to ca23a

The change affects 3 systems.

Changed systems: docs, README.md, tools

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — docs (service) was modified; 14 changed files map to changed impact.
  • observed — README.md (service) was modified; 1 changed file maps to changed impact.
  • observed — tools (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in README.md: Replaces the agent-memory experimental v0.0 introduction and status description with an overview of persistent semantic-view memory, the Claude-, Mem0-, and Zep-style memories, shared benchmarks, and an architecture image.
  • observed — Modified behavior in README.md: Replaces the old quick-start and runtime caveats with Python 3.12+ and uv installation instructions, separate benchmark dependency environments for Claude/Zep and Mem0, storage prerequisites, and credential setup. The previous description of in-memory execution and unsupported operators is removed.
  • observed — Modified behavior in README.md: Replaces the old code-oriented quick start, retrieval implementation details, and LOTUS HelloWorld instructions with a real-model ClaudeMemory example using LotusAdapter. It explains that add() maintains declared views and query() retrieves context without generating an answer, and points to the interface smoke and operator guides.
  • observed — Modified behavior in README.md: Replaces the old project file-structure and smoke-test documentation with a LOCOMO benchmark workflow covering bundle preparation, execution, supported system selectors, output-directory guidance, and the experiment guide. It notes that preparation may download data and running invokes paid APIs.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main changes: refreshed public documentation and benchmark setup guidance.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@SleepyLGod SleepyLGod self-assigned this Oct 4, 2026
@SleepyLGod SleepyLGod added the documentation Improvements or additions to documentation label Oct 4, 2026
@SleepyLGod SleepyLGod changed the title Refresh public documentation and benchmark setup Refresh public documentation and benchmark setup docs Oct 4, 2026
@SleepyLGod SleepyLGod changed the title Refresh public documentation and benchmark setup Refresh public documentation and benchmark setup docs Oct 4, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ca23a40d90

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread .gitignore Outdated
Comment thread docs/design/operator-api.md Outdated
Comment thread tools/evaluation/README.md Outdated
Comment thread tools/evaluation/README.md Outdated
Document direct semantic-join maintenance settings and generated case directories.
Add the MemoryAgentBench tokenizer setup command.
Remove obsolete ignore exceptions while retaining local experiment notes.

Signed-off-by: Von <haodong.lu.me@gmail.com>

@SleepyLGod SleepyLGod left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK

@SleepyLGod
SleepyLGod merged commit 747a1dd into main Oct 4, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants