This directory is a sanitized public review stub for Reddit's Developer Registration / Data API approval process.

It is intended to be copied into a separate public repository and shared with Reddit reviewers.

This is not the full production repository.

The production implementation lives in a private repository. This public stub exists so Reddit can review:

• what the app does
• how mentions are detected
• which Reddit APIs are called
• what data is stored
• what guardrails exist

No credentials, secrets, or internal-only infrastructure details are included here.

This bot is operated by WorldBrain as part of the Memex Garden product.

Contact and operator identity are provided directly in Reddit's registration form. This repository is intended to document behavior and API usage for review.

This app runs the Memex Garden Reddit mention bot. It responds only when a user explicitly mentions the bot in a public thread comment.

The bot:

• polls for new mentions using the Reddit Data API via PRAW
• inspects the direct parent of the mention
• interprets the instruction written in the mention comment
• posts an acknowledgement reply quickly
• edits or follows up with the final bot response

The bot does not:

• scrape Reddit broadly
• send private messages
• vote
• manipulate karma
• post unsolicited comments
• reply unless it is explicitly mentioned

The current implementation supports a small command set:

• summarize the parent comment or submission
• generate a transcript if the parent submission contains transcribable media

The bot only looks at:

• the mention comment
• the direct parent comment or submission
• the containing submission metadata needed to understand context

• Listener worker:
  • hosted as an always-on worker process
  • polls mentions roughly once per second
  • normalizes the mention payload
  • sends the payload to a backend ingest endpoint
• Backend:
  • validates the ingest request
  • persists a mention row
  • posts an immediate acknowledgement
  • performs the heavier processing asynchronously
  • edits the acknowledgement into the final result or adds follow-up replies

• Worker host: Railway
• Backend host: Supabase Edge Functions + application backend

This split keeps the mention listener lightweight while leaving processing, storage, and retries to backend infrastructure.

The app stores only the minimum data needed to process and audit a mention:

• mention comment ID and permalink
• mention text
• mention author username and ID when available
• subreddit name
• submission ID and permalink
• a normalized snapshot of the direct parent comment or submission
• status fields for ack / processing / replied / failed

The app does not intentionally ingest or retain unrelated Reddit content.

The intended rollout is conservative:

• start behind a subreddit allowlist during beta
• respond only when explicitly mentioned
• avoid posting outside the direct mention thread
• keep request volume low and within Reddit rate limits

• The bot only acts on explicit mentions.
• The bot can start behind a subreddit allowlist.
• The bot discloses that it is an automated reply.
• The worker marks mentions as read only after successful backend acceptance.
• The worker uses one listener process to avoid duplicate handling.
• The worker backs off when rate-limit budget falls.
• The bot avoids direct messages and other high-risk actions.

This public stub includes:

• a documented listener example in src/reddit_mention_listener.py
• a documented Reddit write example in src/reddit_write_api_example.py
• an API inventory in API_USAGE.md
• a sanitized environment variable list in .env.example

Sanitized review stub for a Reddit mention bot that listens for explicit mentions and replies to the direct parent context using the Reddit Data API.