hypermnesic 0.1.0__tar.gz

hypermnesic-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "hypermnesic",
+  "metadata": {
+    "description": "hypermnesic — the git-native memory layer. A skillset + a lightweight auto-recall hook + a self-hosted tailnet MCP, so coding agents reach durable memory by default."
+  },
+  "owner": {
+    "name": "Leonard Sellem",
+    "email": "leonard@sellem.me"
+  },
+  "plugins": [
+    {
+      "name": "hypermnesic",
+      "source": "./plugin/plugins/hypermnesic",
+      "category": "productivity",
+      "tags": ["memory", "knowledge", "mcp", "search", "git", "tailnet"]
+    }
+  ]
+}

hypermnesic-0.1.0/.env.example

@@ -0,0 +1,31 @@
+# Copy to .env (gitignored) and fill in. All secrets are read from the environment /
+# this file only — never written to the index, audit log, or any structured output
+# (credential discipline). Leave a var empty to disable that path. NEVER commit real
+# values. See docs/reference/configuration.md.
+
+# --- Embeddings (required for dense retrieval) ------------------------------------
+# The OpenAI API key for text-embedding-3-large. Without it, retrieval degrades to
+# lexical-only (and the test suite runs in exactly that offline mode).
+OPENAI_API_KEY=
+
+# --- Remote client wiring (Claude Code / Codex plugin) ----------------------------
+# Point the plugin at YOUR hypermnesic endpoint, e.g. https://YOUR-HOST.ts.net/mcp .
+# The bundled .mcp.json templates the URL from this var; OAuth is via browser
+# discovery, so the MCP wiring itself needs no token.
+HYPERMNESIC_MCP_URL=
+
+# --- Auto-recall hook on a remote device (optional) -------------------------------
+# The per-prompt recall hook reads this bearer token for its bounded read on a remote
+# (non-tailnet) device. Leave empty to use the tailnet read route instead.
+HYPERMNESIC_MCP_TOKEN=
+
+# --- Public cloud endpoint operator (serve-cloud / setup) -------------------------
+# The operator approval token that gates every public connection. Read from the
+# environment ONLY (never a CLI flag — it would leak via the process table / logs).
+# Generate one with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+HYPERMNESIC_CLOUD_APPROVAL_TOKEN=
+
+# Optional: scopes requested by default when a dynamic OAuth client omits scope.
+# Default is read. Use read,write when you want new connector approvals to ask for
+# both read access and commit_note write access on the consent screen.
+HYPERMNESIC_DEFAULT_CLIENT_SCOPES=read

hypermnesic-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,25 @@
+# Code owners — review routing. The owner is requested for review on any change to
+# these paths. Security-sensitive surfaces (auth, the MCP server, the write path, the
+# protected-path/governance guard) and the security/license docs route here.
+
+# Default owner for everything.
+*                                   @leonardsellem
+
+# Security-sensitive engine surfaces.
+/src/hypermnesic/auth.py            @leonardsellem
+/src/hypermnesic/auth_cloud.py      @leonardsellem
+/src/hypermnesic/mcp_server.py      @leonardsellem
+/src/hypermnesic/commit_note.py     @leonardsellem
+/src/hypermnesic/serialize.py       @leonardsellem
+/src/hypermnesic/frontmatter_gate.py @leonardsellem
+/src/hypermnesic/audit_log.py       @leonardsellem
+
+# Security, license, and contribution policy.
+/SECURITY.md                        @leonardsellem
+/LICENSE                            @leonardsellem
+/CONTRIBUTING.md                    @leonardsellem
+/docs/threat-model-commit-note.md   @leonardsellem
+/docs/launch/                       @leonardsellem
+/scripts/license_scan.py            @leonardsellem
+/scripts/preflight_public_scan.py   @leonardsellem
+/.github/                           @leonardsellem

hypermnesic-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Report something that isn't working as documented
+title: "[bug] "
+labels: bug
+assignees: ""
+---
+
+## What happened
+
+A clear description of the bug and what you expected instead.
+
+## Steps to reproduce
+
+1. …
+2. …
+
+## Deployment shape
+
+Help us reproduce — hypermnesic's behavior depends on how it's deployed:
+
+- **hypermnesic version:** (`hypermnesic --version`)
+- **How you're running it:** self-hosted endpoint / local CLI only / plugin client
+- **Engine host OS:** (e.g. Ubuntu 24.04, macOS 14)
+- **Client:** (Claude / ChatGPT connector, Claude Code plugin, Codex, Obsidian companion, CLI)
+- **Vault size:** approximate number of markdown files
+- **Serving lane:** unified public OAuth `/mcp` (Funnel) / tailnet read companion (`:8848`) / local CLI
+- **Tailscale / Funnel state:** (e.g. `tailscale status` healthy? Funnel configured?)
+- **Embeddings:** `OPENAI_API_KEY` set, or running lexical-only / degraded?
+
+## Logs / output
+
+Paste relevant output. **Redact any tokens, hostnames, or IPs** — never paste secrets.
+
+## Additional context
+
+Anything else that might help.

hypermnesic-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/leonardsellem/hypermnesic/security/advisories/new
+    about: Do NOT open a public issue for security problems. Report privately — see SECURITY.md.
+  - name: Question / discussion
+    url: https://github.com/leonardsellem/hypermnesic/discussions
+    about: For questions and open-ended discussion rather than a specific bug or feature.

hypermnesic-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+title: "[feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem / motivation
+
+What are you trying to do that hypermnesic doesn't support today? What's the
+underlying need (not just the proposed solution)?
+
+## Proposed solution
+
+What you'd like to see. If it touches the retrieval engine, the write path, the
+serving topology, or the plugin/companion, say which.
+
+## Alternatives considered
+
+Other approaches you've thought about, and why they fall short.
+
+## Fit with the project's identity
+
+hypermnesic is a git-first, files-are-truth memory layer with a disposable index.
+Does this proposal keep that invariant? (See [`ARCHITECTURE.md`](../../ARCHITECTURE.md)
+and [`docs/why-hypermnesic.md`](../../docs/why-hypermnesic.md).)
+
+## Additional context
+
+Anything else — links, examples, prior art.

hypermnesic-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+<!-- Thanks for contributing! Keep PRs focused. See CONTRIBUTING.md and AGENTS.md. -->
+
+## What & why
+
+Briefly describe the change and the problem it solves. Link any issue or plan
+(`docs/plans/…`).
+
+## Gates (must pass — same as CI's `lint-test-license` job)
+
+- [ ] `uv run ruff check .`
+- [ ] `uv run python scripts/check_version_consistency.py`
+- [ ] `uv run pytest` (new behavior is covered by a test — test-first)
+- [ ] `uv run python scripts/license_scan.py` (no new AGPL/GPL/SSPL dependency)
+- [ ] `uv run python scripts/preflight_public_scan.py` (no operator host/IP/token/secret added)
+
+## Security surface
+
+- [ ] This PR does **not** touch auth (`src/hypermnesic/auth*.py`), the MCP server,
+      the write path (`commit_note` / `serialize` / `frontmatter_gate`), or the
+      protected-path / governance guard.
+- [ ] If it does: I referenced the relevant `SECURITY.md` / threat-model entry, and a
+      CODEOWNER review is requested.
+
+## Docs
+
+- [ ] User-facing changes are reflected in the docs (README / references / guides /
+      `CHANGELOG.md`), and any tool/CLI/config surface change updates the matching
+      reference doc.
+
+## Sign-off
+
+- [ ] My commits are signed off (`git commit -s`) per the DCO (see `CONTRIBUTING.md`).

hypermnesic-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-test-license:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Sync (dev extras)
+        run: uv sync --extra dev
+      - name: Ruff
+        run: uv run ruff check .
+      - name: Version consistency (pyproject ↔ manifests ↔ __init__)
+        run: uv run python scripts/check_version_consistency.py
+      - name: Tests
+        run: uv run pytest
+      - name: License gate (zero AGPL/GPL/SSPL)
+        run: uv run python scripts/license_scan.py
+      - name: Preflight public scan (no operator secret/host in the to-be-public surface)
+        run: uv run python scripts/preflight_public_scan.py

hypermnesic-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: release
+
+# Publish the hypermnesic engine to PyPI via OIDC Trusted Publishing.
+#
+# Trusted Publishing exchanges a short-lived GitHub OIDC token for a PyPI upload
+# token at run time — there is NO long-lived PyPI API token stored in repo secrets
+# (honours the "never echo secrets" rule in AGENTS.md / CONTRIBUTING.md).
+#
+# One-time operator setup (see PR / LS-1684) before this can publish:
+#   1. Create the `hypermnesic` project on PyPI, OR add a *pending* Trusted Publisher.
+#   2. On PyPI → project → Publishing, add a Trusted Publisher with:
+#        owner            = leonardsellem
+#        repository       = hypermnesic
+#        workflow         = release.yml
+#        environment      = pypi            (must match the `environment:` below)
+#   3. First publish: push a version tag (e.g. `v0.1.0`) or run this workflow via
+#      "Run workflow" (workflow_dispatch). The build version comes from pyproject.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Verify version consistency (pyproject ↔ manifests ↔ __init__)
+        run: uv run python scripts/check_version_consistency.py
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI (Trusted Publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hypermnesic
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing — no stored API token
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hypermnesic-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# hypermnesic engine state (disposable, rebuildable index) — never tracked.
+.hypermnesic/
+
+# Secrets — the OpenAI key lives in .env (env/secrets only; never committed).
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+
+# Corpus-derived evaluation data — NEVER committed. These are generated locally
+# by the harness tools over a private corpus and may contain real names, paths,
+# and queries. The repo ships only the generic tooling + a synthetic example.
+harness/queries.frozen.jsonl
+harness/gbrain_baseline.frozen.jsonl
+harness/results/
+harness/review*.md
+
+# LongMemEval harness — the downloaded dataset (referenced by hash, never
+# committed: ~GBs + contamination, R15) and all generated artifacts. The repo
+# ships only the tooling, the committed manifest, the synthetic smoke subset, and
+# aggregate/per-ability results in harness/BENCHMARKS.md.
+harness/longmemeval/longmemeval_*.json
+harness/longmemeval/corpus/
+harness/longmemeval/results/
+harness/longmemeval/*.frozen.jsonl
+harness/longmemeval/.embed_cache.sqlite
+
+# Local index / scratch artifacts
+*.db
+*.sqlite
+*.sqlite3
+.pytest_cache/
+.ruff_cache/

hypermnesic-0.1.0/.linear.toml

@@ -0,0 +1,3 @@
+workspace = "ls-ventures"
+team_id = "LS"
+vcs = "git"

hypermnesic-0.1.0/AGENTS.md

@@ -0,0 +1,168 @@
+# AGENTS.md
+
+## Linear Task Creation
+
+Every Linear task or subtask created by an agent must be fully documented at creation time with a state-of-the-art description: context, intent, acceptance criteria, validation plan, and handoff/deployment notes when relevant.
+
+Required creation metadata is non-negotiable: effort estimate, priority, and dependency relations (`blockedBy` / `blocks`) mapped from the plan, parent issue, or nearest sibling. If a connector cannot set one of those fields during creation, state the gap immediately and fill it through the next available Linear surface before handoff.
+
+
+Contract for AI coding agents (Claude Code, Codex, and similar) working in this
+repository. Humans: see [`CONTRIBUTING.md`](CONTRIBUTING.md) — the two are consistent;
+this file states the parts an autonomous agent most needs up front.
+
+> [`CLAUDE.md`](CLAUDE.md) is a **symlink to this file** — the two are one document, not
+> two. Edit `AGENTS.md`; the mirror follows. (These governance files are themselves
+> protected by the write guard — they are **refused** by the `commit_note` memory write
+> path and can only be changed in an ordinary, reviewed PR.)
+
+## The prime invariant
+
+**Files are the source of truth; the index is a disposable, rebuildable projection of
+the git tree.** Never treat the index as a database of record. A reindex must never be
+able to lose a committed write. Everything in [`ARCHITECTURE.md`](ARCHITECTURE.md)
+follows from this one line.
+
+## Repo map — where things live
+
+| Area | Path | What it is |
+|---|---|---|
+| Engine source | `src/hypermnesic/` | The Python package (details below) |
+| Retrieval | `retrieve.py`, `index.py`, `embed.py`, `graph.py`, `converge.py` | Hybrid FTS5 + sqlite-vec search; read-time convergence |
+| Write path | `commit_note.py`, `serialize.py`, `frontmatter_gate.py`, `audit_log.py` | The one git-first write, its guards, its gate, its log |
+| Serving | `mcp_server.py`, `auth.py`, `auth_cloud.py` | Public OAuth `/mcp` + tailnet read companion |
+| Local surface | `cli.py` | The engine-host-local `hypermnesic` CLI |
+| Provisioning / config | `install.py`, `connect.py`, `config.py` | Roles, setup, env-driven config |
+| Human surfaces | `capture.py`, `salience.py`, `nav_surface.py`, `think.py`, `propose.py`, `expand.py`, `sidecar.py`, `folders.py`, `generated.py` | Capture/triage, digest, navigation, thinking-mode, sidecar extraction |
+| Tests | `tests/` | `pytest`, `--import-mode=importlib` |
+| Gate scripts | `scripts/` | `check_version_consistency.py`, `license_scan.py`, `preflight_public_scan.py` |
+| Plugin | `plugin/` | Claude Code / Codex plugin (OAuth-discovery, distribution-generic) |
+| Companion | `obsidian-plugin/` | Read-only Obsidian companion (ships from a **separate** GPL-3.0 repo) |
+| Benchmarks | `harness/` | LongMemEval harness + `harness/BENCHMARKS.md` |
+| Docs | `docs/` | Start at [`docs/README.md`](docs/README.md) — it pins current truth |
+
+## Build, test, and gates
+
+Python ≥ 3.11, [uv](https://docs.astral.sh/uv/) for dependencies. The full gate set —
+identical to CI's single `lint-test-license` job — is:
+
+```sh
+uv sync --extra dev
+uv run ruff check .                                   # lint (line-length 100; E,F,I,UP,B)
+uv run python scripts/check_version_consistency.py    # pyproject ↔ manifests ↔ __init__
+uv run pytest                                         # full suite (offline, deterministic)
+uv run python scripts/license_scan.py                 # zero AGPL/GPL/SSPL *dependency* gate
+uv run python scripts/preflight_public_scan.py        # no operator secret/host in the public surface
+```
+
+All six must pass before a change is done. The suite runs offline and deterministic
+(the OpenAI key is neutralized in tests; dense retrieval degrades to lexical).
+
+## Working rules
+
+- **Test-first.** No new production behavior without a failing test first. Tests live
+  in `tests/`, run with `--import-mode=importlib`.
+- **No "pre-existing" failures.** A red test is either fixed in your change or filed as a
+  tracked issue — never dismissed or deleted.
+- **Branch off `main`; never commit to `main` directly.** Use a worktree per task when
+  changes could conflict. Commit per logical unit with a conventional subject and a
+  `Signed-off-by:` DCO line (`git commit -s`).
+- **Permissive dependencies only.** Any new dependency must keep
+  `scripts/license_scan.py` green (zero AGPL/GPL/SSPL). The gate is dependency-scoped;
+  it does not constrain the engine's own (planned-AGPL) license.
+- **Never echo secrets.** The OpenAI key, OAuth consent secret, and tokens are read
+  from the environment / a gitignored `.env` only — never written to the index, the
+  audit log, any output, or chat. `scripts/preflight_public_scan.py` enforces that no
+  operator host/IP/token ships in the public surface — so **use placeholders**
+  (`<your-host>.ts.net`, the `100.64.0.0/10` CGNAT range), never real operator values,
+  in any doc or fixture.
+- **Respect the write guard.** The write path (`commit_note`) is git-first and bounded
+  by a blocklist (protected-path + governance-file fence). Do not weaken it; changes to
+  `serialize.py` / `frontmatter_gate.py` / `auth*.py` / `mcp_server.py` are
+  security-sensitive (CODEOWNERS-routed) and must cite [`SECURITY.md`](SECURITY.md) and
+  the threat model.
+- **Native primitives first.** Before adding any adapter, wrapper, shell-out, or
+  parser, check whether an upstream tool (the MCP SDK, Tailscale, OAuth libs, uv) already
+  exposes the primitive. Prefer it over re-inventing it.
+
+## Documentation must not drift — NON-NEGOTIABLE
+
+**Documentation is part of the change, not a follow-up.** A change is **not done** until
+every document it affects is corrected **in the same PR**. "Update the docs later" is not
+allowed — later never comes, and a stale doc actively misleads the next agent.
+
+This is not a style preference; it is paid-for scar tissue. This repo has been bitten
+twice: the **0.0.4 ↔ 0.0.5** release that bumped only the Python package and let the
+plugin manifests drift (now caught by `scripts/check_version_consistency.py`), and a
+whole **"Phase A — drift correction"** in [`PR #26`](https://github.com/leonardsellem/hypermnesic/pull/26)
+spent un-stale-ing the "tailnet-only / read-only" self-description and the
+"allowlist-by-default" write model that code had long since moved past. Every hour spent
+there is an hour the rule below would have saved.
+
+### When you change X, update its docs in the same PR
+
+| If your change touches… | …update, in the same PR |
+|---|---|
+| **MCP tool surface** (`mcp_server.py` — add/remove/rename a tool or change args) | [`docs/reference/mcp-tools.md`](docs/reference/mcp-tools.md); the tool list in [`README.md`](README.md); `ARCHITECTURE.md` if the serving picture changes |
+| **CLI** (`cli.py` — commands/flags) | [`docs/reference/cli.md`](docs/reference/cli.md); the CLI examples in [`README.md`](README.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md) |
+| **Config / env** (`config.py`, `.env.example`) | [`docs/reference/configuration.md`](docs/reference/configuration.md); `.env.example`; any `CONVERGE_*`/budget mentions in [`ARCHITECTURE.md`](ARCHITECTURE.md) |
+| **Write guard / protected paths / governance fence** (`serialize.py`, `frontmatter_gate.py`, `commit_note.py`) | `ARCHITECTURE.md` write-path section; [`SECURITY.md`](SECURITY.md) + [`docs/threat-model-commit-note.md`](docs/threat-model-commit-note.md); the write-model pin in [`docs/README.md`](docs/README.md); the write-guard bullet above; `README.md` "How it works" |
+| **Auth / serving topology / lanes** (`auth*.py`, `mcp_server.py`) | `ARCHITECTURE.md` serving section; the serving-topology pin in `docs/README.md`; [`docs/unified-oauth-mcp-deploy-runbook.md`](docs/unified-oauth-mcp-deploy-runbook.md); `README.md`; `SECURITY.md` |
+| **Retrieval / convergence / index** (`retrieve.py`, `converge.py`, `index.py`, `embed.py`, `graph.py`) | `ARCHITECTURE.md` retrieval + convergence sections; `README.md` "How it works" if user-visible; `harness/BENCHMARKS.md` if measured numbers move |
+| **Version** (`pyproject.toml` `[project].version`) | `src/hypermnesic/__init__.__version__` **and the plugin manifests** — do not hand-enumerate them; run `scripts/check_version_consistency.py`, which names every file that must match; plus a dated [`CHANGELOG.md`](CHANGELOG.md) section |
+| **Any new dependency** | keep `scripts/license_scan.py` green; record it in `pyproject.toml` |
+| **New term or concept** | [`GLOSSARY.md`](GLOSSARY.md) |
+| **Renaming / superseding a doc** | the [`docs/README.md`](docs/README.md) index **and** its "current truth" pins; move the superseded doc to `docs/archive/` with a pointer banner to its replacement |
+| **Any user-visible behavior at all** | a dated entry under `[Unreleased]` in [`CHANGELOG.md`](CHANGELOG.md) |
+
+### Anti-drift discipline
+
+- **Point to the enforcing gate; don't re-list the enumerable set.** Where an automated
+  gate already pins truth (versions → `check_version_consistency.py`; copyleft →
+  `license_scan.py`; secrets/hosts → `preflight_public_scan.py`), reference the gate
+  rather than copying its list into prose — a copied list is the next thing to drift.
+- **`docs/README.md` "current truth" is the tie-breaker.** When a process-history doc
+  (a plan, brainstorm, handoff, gate artifact) conflicts with current truth, the pins in
+  [`docs/README.md`](docs/README.md) win. If your change moves current truth, update those
+  pins.
+- **Signed-off reviews are append-only.** Do not rewrite a dated, signed-off security
+  review or gate artifact — add a dated amendment (`amends:` / `signed_off:` frontmatter).
+- **Found drift you didn't cause? Fix it or file it.** Same rule as a failing test — a
+  doc that contradicts the code is a defect, not background noise.
+
+## Linear
+
+- Use `linear-safe` / `linear-ls` for routine interactive issue reads,
+  comments, branch starts, and status changes. Keep Linear MCP as a
+  fallback/lifecycle surface only when a task explicitly requires MCP behavior
+  or wrapper healthchecks fail.
+- The repo-root `.linear.toml` pins `workspace = "ls-ventures"` and
+  `team_id = "LS"` only as a human/raw-CLI fallback. It is not the agent safety
+  boundary because ambient Linear env vars override `.linear.toml`; wrappers
+  remain the agent default.
+
+## How this repo plans and ships work
+
+- **Plans** live under `docs/plans/` (`YYYY-MM-DD-NNN-<type>-<slug>-plan.md`) and are the
+  authoritative scope of record; brainstorms (the "what") live under `docs/brainstorms/`.
+  Both are **process history** — when they conflict with `docs/README.md`'s current
+  truth, the pins win.
+- **Gate artifacts** (`docs/gate-artifacts/`) and dated **security reviews**
+  (`docs/*-security-review.md`, with `amends:` / `signed_off:` frontmatter) record
+  signed-off decisions; reusable design decisions live under `docs/solutions/`.
+- **Release history** is [`CHANGELOG.md`](CHANGELOG.md) (Keep a Changelog format); the
+  narrative build log is `implementation-notes.md` (historical, not a changelog).
+- **Public-launch staging** lives under `docs/launch/` — the AGPL-3.0 text, the one-PR
+  flip runbook, and the launch checklist are staged but **not live**; the `LICENSE` stays
+  proprietary until the flip PR.
+
+## Reference
+
+- Architecture: [`ARCHITECTURE.md`](ARCHITECTURE.md)
+- Documentation index (start here): [`docs/README.md`](docs/README.md)
+- MCP tools: [`docs/reference/mcp-tools.md`](docs/reference/mcp-tools.md)
+- CLI: [`docs/reference/cli.md`](docs/reference/cli.md)
+- Configuration: [`docs/reference/configuration.md`](docs/reference/configuration.md)
+- Security: [`SECURITY.md`](SECURITY.md) · threat model: [`docs/threat-model-commit-note.md`](docs/threat-model-commit-note.md)
+- Glossary: [`GLOSSARY.md`](GLOSSARY.md)
+- Contributing (humans): [`CONTRIBUTING.md`](CONTRIBUTING.md)

hypermnesic-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,128 @@
+# Architecture
+
+This document gives you an accurate mental model of hypermnesic without reading the
+source. For the user-facing quick start see [`README.md`](README.md); for the exact
+tool/CLI/config surfaces see [`docs/reference/`](docs/reference/).
+
+## The one invariant
+
+> **The git-tracked markdown files are the single source of truth. The search/graph
+> index is a disposable, rebuildable projection of the committed tree.**
+
+Everything else follows from this. There is no separate database of record. A reindex
+can be run at any time and **never loses a committed write** — because writes go to git
+first, and the index is rebuilt *from* git. This is what makes the system safe to drop
+into any repo and safe to operate without backups of the index.
+
+## Layers
+
+```mermaid
+flowchart TB
+  subgraph SOT["Source of truth"]
+    G["git-tracked markdown vault<br/>(notes, sources, projects, …)"]
+  end
+  subgraph IDX["Disposable index (a projection of HEAD)"]
+    ING["ingest.py — walk *.md, strip frontmatter, chunk ≤4000"]
+    DB["index.py — SQLite: FTS5 (lexical) + sqlite-vec KNN (dense, 1536-d)<br/>+ SHA checkpoint"]
+    EMB["embed.py — OpenAI text-embedding-3-large @ 1536"]
+    GR["graph.py — wikilink edges"]
+    ING --> DB
+    EMB --> DB
+    DB --> GR
+  end
+  subgraph READ["Read path"]
+    CV["converge.py — catch index up to HEAD + bounded dense fill (every read)"]
+    RT["retrieve.py — RRF fusion of FTS5 + KNN, recency, dedup"]
+    TH["think.py — related notes + Socratic prompts (no write)"]
+    CV --> RT
+  end
+  subgraph WRITE["Write path (git-first)"]
+    CN["commit_note.py — guard → gate → write file → git commit → index follows → audit"]
+    FG["frontmatter_gate.py — diff-or-die"]
+    SE["serialize.py — protected-path + governance fence, within-repo, locks"]
+    AU["audit_log.py — append-only, body-free"]
+    CN --> FG --> SE --> AU
+  end
+  subgraph SERVE["Serving"]
+    M1["public OAuth /mcp (mcp_server.build_cloud_server) — every remote client"]
+    M2["tailnet read companion :8848 (mcp_server.build_server, auth-off, read-only)"]
+    CLI["hypermnesic CLI (cli.py) — engine-host-local"]
+  end
+  G --> ING
+  G -. "HEAD delta" .-> CV
+  CN -->|commit| G
+  READ --> SERVE
+  WRITE --> SERVE
+```
+
+### Retrieval (`retrieve.py`, `index.py`, `embed.py`, `graph.py`)
+
+Hybrid: **SQLite FTS5** (lexical) fused with **sqlite-vec** KNN (dense; OpenAI
+`text-embedding-3-large` at **1536 dims**) via **Reciprocal Rank Fusion**. The dense
+channel degrades gracefully — if the embedding API is unreachable, lexical + graph
+results still return, flagged `degraded_lexical_only`. Near-duplicate hits are collapsed
+and a per-hit write-recency timestamp is attached (consumers derive their own forgetting
+curve). The wikilink **graph** (`graph.py`) answers `build_context` and entity
+`resolve`.
+
+### Read-time convergence (`converge.py`)
+
+Every read first runs `converge()`: it delta-replays the lexical index up to `HEAD`,
+invalidates doc-surface vectors for changed markdown paths, closes a bounded slice of
+the dense lag for both chunks and missing/stale doc surfaces (`CONVERGE_EMBED_BUDGET`),
+and signals (never forces) a manual reindex when `HEAD` has jumped far past the
+checkpoint (`CONVERGE_MAX_DELTA_FILES`). A debounce (`CONVERGE_DEBOUNCE_SECONDS`)
+coalesces bursts. This is the correctness guarantee that lets the index stay a pure
+projection while reads remain fresh — a just-committed or edited note is recall-able on
+the next read with no manual reindex.
+
+### Git-first write path (`commit_note.py`, `serialize.py`, `frontmatter_gate.py`, `audit_log.py`)
+
+`commit_note` is the one sanctioned write. It is **git-first**: write file → `git
+commit` (→ push) → the index follows as a projection. The agent never merges. It is
+bounded by, in order: the **blocklist write guard** (`serialize.py` — protected-path
+refusal for `.git/`, `.github/`, agent-instruction files, `scripts/`/`hooks/`/`skills/`,
+plus a governance-file fence for build/CI/credential files; within-repo resolution,
+no traversal/symlink escape; an optional allowlist to *narrow*); the **diff-or-die
+frontmatter gate** (`frontmatter_gate.py` — any unrequested frontmatter change aborts
+the write); single-writer **locks** (`serialize.py`); and an **append-only audit log**
+(`audit_log.py` — summaries only, never bodies, never credentials). A refusal returns
+`{committed: false, refused: …}` — never a silent success.
+
+### Serving topology — two lanes (`mcp_server.py`, `auth.py`, `auth_cloud.py`)
+
+1. **Public OAuth `/mcp`** (`build_cloud_server`) — the sole network lane for every
+   remote client (ChatGPT/Claude connectors, the Claude Code / Codex plugin, the
+   Obsidian companion). OAuth 2.1 with Dynamic Client Registration + PKCE; an
+   operator-consent gate issues tokens; tokens are audience-bound (RFC 8707) and
+   revocable. The AS metadata advertises both confidential-client methods and the
+   public-client `none` method because Codex/app connectors may register without a
+   client secret. DCR client registrations and live bearer/refresh token state persist
+   in owner-only `.hypermnesic/cloud-oauth-state.json` so refresh survives deploy
+   restarts; `.hypermnesic/client-grants.json` remains a separate secret-free grant
+   metadata surface for owner listing/revocation. Read tools are always available; the
+   gated `commit_note` write tool requires the `write` scope. Exposed via Tailscale
+   Funnel (HTTPS + auto-TLS).
+2. **Tailnet read companion** (`build_server`, `:8848`, auth-off, **read-only**) — for
+   the Obsidian companion and the per-prompt recall hook on tailnet devices; tailnet
+   membership is the boundary. A write-enabled serve requires auth
+   (`write_enabled ⇒ auth-required`) unless the bounded `--allow-tailnet-write` opt-in
+   is used on a CGNAT bind.
+
+The server binds a specific Tailscale interface at the socket level and refuses
+`0.0.0.0` at construction. The CLI (`cli.py`) is the engine-host-local surface and
+skips the network entirely.
+
+### Installer & roles (`install.py`)
+
+`hypermnesic install --role={single|master|client}` and `hypermnesic setup` provision a
+host: render service units, configure the funnel + OAuth discovery, install the
+post-merge convergence hook, and verify the live HTTPS discovery chain before reporting
+success (fail-closed: no partial state).
+
+## Companion
+
+The Obsidian companion (`obsidian-plugin/`, shipped as a separate GPL-3.0 repository) is
+a strictly read-only recall surface that talks to the engine only over the MCP wire
+(`search` / `build_context` / `think`). It is not a derivative of the engine — see the
+license boundary in [`README.md`](README.md).