# GitHub Strategy

**Status:** WORKING INTERNAL STRATEGY  
**Date:** 2026-05-09  
**Applies to:** public `github.com/pgmnemo/pgmnemo` surface  
**Not for publication:** internal operating document

---

## 1. Objective

Use GitHub as the primary trust surface for `pgmnemo`, so the repository itself communicates:

1. technical maturity
2. operational discipline
3. credible differentiation
4. maintainer responsiveness
5. installability and proof

The target is:

> a skeptical PostgreSQL engineer can open the repo, understand what `pgmnemo` is, install it, see evidence that it works, and believe that this project might become the default agent-memory extension for PostgreSQL.

---

## 2. Strategic position

`pgmnemo` should not look like a generic AI tool.
It should look like a serious PostgreSQL extension with a differentiated AI-memory thesis.

Target feel:
- `pgvector` on installation clarity
- `Apache AGE` on identity and docs seriousness
- `pgvectorscale` on benchmark-backed claims
- `TimescaleDB` on onboarding polish and confidence

Avoid looking like:
- a research dump
- a founder notebook
- a loose internal dogfood repo
- a roadmap-heavy project with weak operator proof

---

## 3. Best owner model

### Best single owner

If one agent must own the GitHub surface, the best fit is:

**`growth_lead`**

Reason:
- explicitly owns README, docs, issue templates, positioning, launch, community, and competitive narrative

### Required co-owners

GitHub must not be run by `growth_lead` alone.

Working model:
- Growth Lead — public surface owner
- Technical Lead — release hygiene owner
- Chief Architect — technical claim / compatibility truth owner
- Startup Mentor — external critique owner
- Competitive Intelligence / Literature Scout — competitor watch inputs

This split avoids both failure modes:
1. technically correct but externally unreadable
2. externally polished but internally dishonest

---

## 4. What GitHub must prove

Every GitHub-facing change should strengthen one of these proof classes:

### P1. Install proof

GitHub must answer:
- supported PostgreSQL versions
- supported `pgvector` versions
- Docker path
- native path
- upgrade path
- what is experimental vs stable

### P2. Product proof

GitHub must answer:
- what `pgmnemo` is
- why it is different from `mem0`, `Zep`, `Constructive`, and generic vector stacks
- who it is for
- what exact SQL/API surface is stable today

### P3. Performance / quality proof

GitHub must answer:
- benchmark methodology
- benchmark datasets
- recall / latency / footprint claims
- what has been measured vs inferred

### P4. Maintenance proof

GitHub must answer:
- release cadence
- issue templates
- bug triage expectations
- contribution flow
- upgrade discipline

### P5. Strategic proof

GitHub must answer:
- why this belongs in PostgreSQL
- why provenance-gated memory matters
- why this is a long-term extension product rather than an internal experiment

---

## 5. External benchmark lessons

### `pgvector`

Copy:
- ruthless installation clarity
- many environment paths
- examples before philosophy

### `Apache AGE`

Copy:
- strong project identity
- official documentation anchor
- visible seriousness and ecosystem fit

### `pgvectorscale`

Copy:
- benchmark-backed claims
- clear differentiation
- contributor path separated from user path

### `TimescaleDB`

Copy:
- explicit quickstart
- obvious next steps
- confidence-building onboarding

### `Constructive`

Copy:
- ecosystem framing and getting-started momentum

Do not copy:
- broad platform framing that weakens extension-trust focus

---

## 6. Strategic rules

### Rule 1 — GitHub is a product surface

Treat README, releases, docs, examples, issue templates, and benchmarks as product components.

### Rule 2 — Public contract beats internal progress

If `main` is ahead of the latest release, public docs must still reflect one coherent reality.
No split-brain between:
- README
- release notes
- `CHANGELOG.md`
- `META.json`
- extension control file
- docs examples

Also decide one explicit release model and document it:
- releases are canonical
- or tags are canonical

### Rule 3 — Installation clarity beats feature count

For early adoption, one clean install path is more valuable than many extra features with unclear setup.

### Rule 4 — Benchmarks must be reproducible or omitted

Any performance or recall claim on GitHub must link to:
- dataset
- query protocol
- environment
- command path
- exact metric definition

### Rule 5 — Stable path first, roadmap second

Public docs must lead with:
- what works today
- how to install it
- how to use it safely

### Rule 6 — Every public page must know its audience

- README = first-time evaluator
- INSTALL = operator
- USAGE = implementer
- MIGRATION = adopter
- benchmarks = skeptic
- CONTRIBUTING = contributor

### Rule 7 — Visible maintenance is part of the product

Issue templates, response rhythm, release discipline, compatibility notes, `CODEOWNERS`, `SECURITY.md`, and `CODE_OF_CONDUCT.md` are part of the adoption contract.

### Rule 8 — Technical honesty compounds

Document known limitations directly:
- supported PG versions
- unsupported environments
- performance caveats
- RLS caveats
- non-goals

### Rule 9 — Public repo language must match the extension form factor

Avoid stale language from the pre-extension phase:
- `install.sql`
- `mem.*` wedge-first framing
- internal dogfood jargon
- paper-program language as primary product explanation

### Rule 10 — The repo should look smaller and sharper, not bigger and fuzzier

`pgmnemo` should look like a focused extension with a hard technical thesis.

### Rule 11 — README above-the-fold must route the first four questions

The first visible screen should route a newcomer to:
- Quickstart
- Install / Upgrade
- Examples
- Roadmap / Status

---

## 7. Success condition

GitHub is strategically healthy when:

1. a PostgreSQL engineer can install `pgmnemo` in under 10 minutes
2. a reviewer can tell exactly which version is latest and what changed
3. a skeptical adopter can distinguish stable surface from planned surface
4. a contributor can see how to file issues, propose changes, and run tests
5. a competitor reviewer must concede that the repo looks technically serious

---

## 8. Decision

`pgmnemo` GitHub will be run as a **trust-building technical product surface**.

Permanent owner: `growth_lead`  
Permanent co-owner: `technical_lead`  
Required gate reviewers: `chief_architect`, `startup_mentor`