build(deps): bump actions/setup-python from 5 to 6

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
         python-version: ["3.10", "3.11", "3.12"]
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install (core + server/mcp/code extras; no torch — the offline gate)
@@ -38,7 +38,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.9"
       - name: Install (numpy-only core — the minimum supported runtime)
@@ -57,7 +57,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
       - name: Build sdist + wheel and verify a clean install

.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: release
+
+# Publish Engraphis to PyPI when a GitHub Release is published.
+# Uses PyPI Trusted Publishing (OIDC) — NO API token is stored in the repo.
+# One-time setup before your first tagged release: see docs/RELEASE.md.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}          # also allow a manual run from the Actions tab
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+      - name: Validate metadata (twine check)
+        run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi            # configure this env name on the PyPI trusted publisher
+    permissions:
+      id-token: write            # REQUIRED for trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

docs/LAUNCH-POST.md

@@ -0,0 +1,121 @@
+# Engraphis — Launch copy (paste-ready)
+
+Built from your own landing page + GTM positioning. Post the code publicly and get
+`pip install engraphis` working **first** — every version below assumes a stranger can try it
+in one command. Fill the two brackets (`REPO_URL`, `DEMO_URL`) and go.
+
+---
+
+## 1. Show HN (Hacker News)
+
+**Title:**
+`Show HN: Engraphis – local-first memory for AI coding agents (MCP, no cloud)`
+
+**Body:**
+```
+Every new session, my coding agent started from zero — re-asking what package manager I use,
+re-learning the codebase, forgetting past decisions. The hosted memory services fix this by
+making you ship your context to their cloud and bill per memory. I wanted the opposite, so I
+built Engraphis.
+
+It's a local-first memory engine for agents. The core is 100% on your machine (SQLite + local
+embeddings, numpy-only), Apache-2.0, no API key for memory, no per-token cost, no data leaving
+your box. You bring your own LLM only for optional chat/synthesis.
+
+The headline is a native MCP server — `claude mcp add engraphis -- engraphis-mcp` — so Claude
+Code, Cursor, Cline, Zed, and Windsurf plug in and stop forgetting across sessions and repos.
+
+What's actually different under the hood:
+- Bi-temporal facts: contradictions get versioned (valid_from/valid_to), not clobbered — you
+  can ask "why do we know this?" and "what did we believe as of last week?"
+- Hybrid recall: vector + keyword + a knowledge graph (Personalized PageRank), fused and reranked.
+- An Ebbinghaus forgetting curve so stale facts decay and reinforced ones stick.
+- Code-aware: it indexes a repo into a function/class/call graph so "what calls this?" is cheap.
+
+Try it in ~2 min:
+  pip install engraphis
+  claude mcp add engraphis -- engraphis-mcp
+
+Repo: REPO_URL
+60-sec demo: DEMO_URL
+
+It's early (v0.1, beta) and I'd love feedback — especially on recall quality vs. mem0/Zep/Letta
+and on what you'd need before trusting it with a real project's memory.
+```
+*Post Tue–Thu, ~8–10am ET. Reply to every comment for the first few hours — HN rewards presence.*
+
+---
+
+## 2. Reddit (r/LocalLLaMA, r/ClaudeAI, r/cursor)
+
+**Title:**
+`I built a local-first memory engine for coding agents — MCP server, runs on your machine, no per-token cost`
+
+**Body:**
+```
+My agents kept forgetting everything between sessions, and I didn't want to send my private
+codebase context to a hosted memory cloud that bills per memory. So I made Engraphis — a
+self-hosted memory engine with a native MCP server.
+
+- Local + private: SQLite + local embeddings, offline by default, Apache-2.0.
+- Plugs into Claude Code / Cursor / Cline / Zed / Windsurf via MCP (`remember` / `recall`,
+  scoped to workspace → repo → session).
+- Actually remembers the right things: hybrid recall (vector + keyword + graph), an Ebbinghaus
+  decay curve, and bi-temporal truth so contradictions are versioned instead of overwritten.
+- There's a Memory Inspector UI where you can see exactly when/why a fact changed.
+
+Install:
+  pip install engraphis
+  claude mcp add engraphis -- engraphis-mcp
+
+Repo + 60s demo in the comments. It's v0.1 and I'm looking for honest feedback — what would you
+need before you'd let it hold your project's memory?
+```
+*Put the links in the first comment, not the post body — several of these subs down-rank link posts.*
+
+---
+
+## 3. X / Twitter thread
+
+```
+1/ Your AI coding agent forgets everything between sessions.
+
+Hosted memory tools "fix" this by making you ship your context to their cloud and billing you
+per memory.
+
+I built the opposite: Engraphis — local-first memory that runs on your machine. Free core, open
+source. 🧵
+
+2/ One command to give any MCP agent long-term memory:
+
+  pip install engraphis
+  claude mcp add engraphis -- engraphis-mcp
+
+Works with Claude Code, Cursor, Cline, Zed, Windsurf. Your data never leaves your box.
+
+3/ It's not just a vector store:
+• bi-temporal facts (contradictions are versioned, not clobbered — ask "why do we know this?")
+• hybrid recall: vector + keyword + knowledge graph
+• an Ebbinghaus forgetting curve so stale facts fade, reinforced ones stick
+• indexes your repo's call graph
+
+4/ There's also a Memory Inspector UI: search, timeline, and the exact word-level diff of when a
+fact changed and why.
+
+60-second demo: DEMO_URL
+
+5/ It's early (v0.1) and open source (Apache-2.0). Repo + docs: REPO_URL
+
+If your agent keeps re-learning your codebase, I'd love for you to try it and tell me where recall
+falls short.
+```
+
+---
+
+## Notes
+- Everything above is claims your README already backs up. Don't add benchmarks you haven't run
+  honestly — "v0.1, looking for feedback" is a stronger and safer launch posture than big numbers.
+- Pick **one** primary channel for launch day (Show HN is the highest-leverage for a dev tool).
+  Post the others the same week, not the same hour.
+- The single biggest predictor of a good launch here is the **60-second demo video**. Make that
+  before you write another word.

docs/MONETIZATION-FAST.md

@@ -0,0 +1,67 @@
+# Engraphis — Making money faster (freemium, done right)
+
+Your instinct is correct: **free trial → subscribe** is the right model. One correction saves you
+from killing your own product — **do not put the usage limit on the local core.** Here's why, then
+exactly where the paywall goes and how to get cash fastest.
+
+## Why not limit the local engine
+1. **It's unenforceable.** The core is Apache-2.0 and runs on the *user's* machine. Anyone can read
+   the code and delete the limit, or fork it. A cap there is theater.
+2. **There's no cost to recoup.** mem0 and Zep meter you because *they* pay for the servers your
+   memories live on. Engraphis's free core runs on the user's own hardware — you pay nothing per
+   memory, so there's nothing to bill back. A limit there is pure friction that kills adoption and
+   throws away your one winning line — *"no per-token cost, no metering"* — the exact thing that
+   beats mem0 and fills the gap Zep left when it dropped self-hosting.
+
+The limit belongs where you **actually bear cost and can enforce it**: hosted sync, team memory,
+and closed-source Pro add-ons.
+
+## The model — same "try free → subscribe," placed correctly
+
+| Tier | Price (anchored to competitors) | What's in it | Where the limit lives |
+|---|---|---|---|
+| **Free** (local, OSS, unlimited) | $0 | Engine + MCP server + CLI + single-user local Inspector. Yours forever, on your machine. | None — this is the trial that hooks them |
+| **Pro** (individual) | ~$15–19/mo or **$99/yr founding** | Hosted memory **sync across your devices**, cloud backup, Inspector Pro dashboard, priority support | Free = 1 device / small sync quota → Pro = unlimited |
+| **Team** | ~$25–40/seat/mo | **Shared team memory**, RBAC/SSO, audit exports, encryption-at-rest | Per seat |
+| **Cloud / Enterprise** (later) | custom | Managed hosting, SLA, on-prem help | — |
+
+The "try it, then subscribe" path stays intact: they run the free local tool, love it, and the
+moment they want their memory **on their laptop *and* desktop, backed up, or shared with a
+teammate** — that's the wall, and it's one worth paying to cross. Price it flat and undercut mem0
+($19/$79/$249); "no per-memory metering" *is* your ad.
+
+> Prices anchored to your own GTM table (mem0 $19/$79/$249, Letta $20, Zep $125+). Re-check before
+> publishing — they move.
+
+## What to build first for money
+**Multi-device / team memory sync.** It's the natural upgrade (persistent memory that people
+immediately want *everywhere*), it's server-side so the limit is real, and your GTM already named
+it as the Pro wedge. Your Memory Inspector already exists — hosting it as the Pro dashboard is a
+fast paid surface. Roughly 2–4 focused weeks *after* launch. Don't start it until the free tool is
+live and getting users.
+
+## Fastest actual cash — in order (the "faster" you asked for)
+Subscriptions need volume to matter (2% of 50 users = 1 customer), so the fast money at launch
+isn't the subscription — it's capturing *committed demand*:
+
+1. **Founding-member prepay (launch day).** Stand up a Stripe/Gumroad link:
+   *"Engraphis Pro — Founding: $99/yr, locked forever, hosted sync the day it ships."* You collect
+   real cash and validate willingness-to-pay **before** building the cloud. Single fastest honest
+   dollar — and the prepay count tells you whether Pro is even worth building.
+2. **GitHub Sponsors** — already configured in `FUNDING.yml`. Turn on tiers; announce it in the
+   launch post. Small but immediate.
+3. **Paid setup/tuning for teams** — *"I'll deploy + tune Engraphis for your team, $X."* Fastest
+   dollars-per-hour for a technical founder; doesn't scale, but it funds runway and puts you in the
+   room with your first paying teams.
+
+## Sequencing
+Launch free → capture founding prepay + waitlist on day one → build team/multi-device sync as the
+first paid feature → convert the waitlist. **Distribution first; monetize the demand.** Trying to
+charge before anyone uses it is exactly why it feels stuck.
+
+---
+*Not legal or financial advice. You can keep the core Apache-2.0 and ship Pro features as a
+separate, commercially-licensed package (`engraphis-pro`) — Apache is permissive, so new code can
+carry your terms while the open core stays open. If you ever accept outside code contributions,
+use a contributor agreement so you retain the right to do this — looks solo today, so low risk.
+Validate the "Engraphis" trademark and your license terms with a professional before charging.*

docs/RELEASE.md

@@ -0,0 +1,85 @@
+# Releasing Engraphis to PyPI
+
+Goal: make `pip install engraphis` work for a stranger. The name is **free** on PyPI as of
+2026-07-03. Do this once and Week 2 of the ship plan is done.
+
+There are two paths. **First release → do Path A (manual, 10 min).** Every release after →
+Path B is automatic (`release.yml` is already committed; you just publish a GitHub Release).
+
+---
+
+## 0. Pre-flight fixes (5 min, do these first)
+
+- [ ] **Fix the project URLs.** `pyproject.toml [project.urls]` points at
+      `github.com/engraphis/engraphis`, but the repo is at `github.com/Coding-Dev-Tools/engraphis`.
+      Either update the three URLs to the real remote, **or** create an `engraphis` GitHub org and
+      move the repo there (nicer branding, and the URLs already assume it). Broken links on the
+      PyPI page look abandoned — fix before publishing.
+- [ ] **Confirm version.** `version = "0.1.0"` is fine for the first upload. Bump it for every
+      later release (PyPI refuses to overwrite an existing version).
+- [ ] **Confirm `LICENSE` and `README.md` exist at repo root** (they do) — PyPI renders the README
+      as the project page.
+- [ ] Merge your working branch to `main` and push, so you're releasing the real code.
+
+---
+
+## Path A — First release (manual, with an API token)
+
+The first upload has to create the project, so do it by hand once.
+
+```bash
+cd C:\GitHub\engraphis
+python -m pip install --upgrade build twine
+python -m build                      # writes dist/engraphis-0.1.0.tar.gz + .whl
+twine check dist/*                   # metadata sanity check — must say PASSED
+```
+
+Get a token: log in at https://pypi.org → Account settings → **API tokens** → *Add token*
+(scope: "Entire account" for the first upload; you can scope it to the project afterward).
+
+```bash
+twine upload dist/*
+# username:  __token__
+# password:  pypi-AgEI...   (paste the token)
+```
+
+Verify in a clean environment:
+
+```bash
+python -m venv /tmp/e && /tmp/e/Scripts/activate   # (Windows: \tmp\e\Scripts\activate)
+pip install engraphis
+engraphis-mcp --help                 # the headline command exists → success
+```
+
+Then delete the token if it was account-scoped, and switch to Path B for everything after.
+
+---
+
+## Path B — Every release after (automatic, no tokens)
+
+`release.yml` publishes via **PyPI Trusted Publishing (OIDC)** — no secrets stored. One-time setup:
+
+1. On PyPI → your project → **Manage → Publishing → Add a trusted publisher → GitHub**. Enter:
+   - Owner: `Coding-Dev-Tools` (or your `engraphis` org)
+   - Repository: `engraphis`
+   - Workflow filename: `release.yml`
+   - Environment name: `pypi`   ← must match the `environment:` in the workflow
+2. In the GitHub repo → **Settings → Environments → New environment → `pypi`**. (Optionally add a
+   required-reviewer rule so a release waits for your one-click approval — a nice safety gate.)
+
+To cut a release from then on:
+
+```bash
+# bump version in pyproject.toml first, commit, then:
+git tag v0.1.1 && git push origin v0.1.1
+```
+
+Then on GitHub → **Releases → Draft a new release** → pick the tag → **Publish**. The workflow
+builds, runs `twine check`, and publishes to PyPI automatically.
+
+---
+
+## After it's live
+- [ ] Update the README install line from `pip install -e .` to `pip install engraphis`
+      (and `pip install "engraphis[mcp]"` for the MCP server).
+- [ ] Tweet/post the one command. "`pip install engraphis`" *is* the launch — see `LAUNCH-POST.md`.