RDF/XML serialization is deferred.
{
"@context": {
"schema": "https://schema.org/",
"wiki": "https://wazootech.github.io/wiki/",
"foaf": "http://xmlns.com/foaf/0.1/",
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"owl": "http://www.w3.org/2002/07/owl#",
"dc": "http://purl.org/dc/elements/1.1/",
"dcterms": "http://purl.org/dc/terms/",
"sh": "http://www.w3.org/ns/shacl#",
"wazoo": "https://schema.wazoo.dev/"
},
"@id": "wiki:Memory_Repo_Best_Practices",
"@type": "schema:TechArticle",
"schema:articleBody": "# Memory Repo Best Practices\n\nA **memory repo** is a per-owner wiki graph repository that is the durable store for one owner or organization's knowledge: typed wiki pages, per-source immutable datasets, connector code, and validation all live in one repository. This is the \"wiki repository memory-first\" model. This document is the spec that the [memory-first wiki repos issue](https://github.com/wazootech/wiki/issues/261) implements and that [connector memory wiring](https://github.com/EthanThatOneKid/ethanpedia/issues/45) builds against.\n\n## Model\n\nThe wiki repository _is_ the memory. There is no separate data tier: raw captures, normalized records, cursors, and bookkeeping live in the same repository as the knowledge graph, so the graph and its sources cannot drift.\n\n```\nEthanThatOneKid/\n .github/ # identity, meta, policies (uniform owner special repo)\n workspace/ # dev-surface harness (uniform owner special repo)\n memory/ # the memory wiki repo (uniform owner special repo)\n```\n\n## Naming\n\n- **Uniform per-owner name:** the memory repo is named `memory` under each owner or organization, joining `.github` and `workspace` as the third uniform owner special repo. Examples: `EthanThatOneKid/memory`, `wazootech/memory`.\n- **Role suffix:** the `-pedia` suffix previously designated knowledge repos (`ethanpedia`, `wazoopedia`). Going forward it describes the memory role: data repositories use the `memory` family, not `-pedia`. The `wazoopedia` repo has been renamed to `memory`.\n- **Per-source datasets are subtrees**, not repositories: `raw/<source>/` inside the memory repo.\n- **Escape hatch:** if a single source outgrows the shared repo (volume, access control, or CI isolation), split that subtree to a per-source repo named `<product>-<source>-memory` (e.g. `ethanpedia-calendar-memory`). Do not split preemptively.\n- **Transcription:** repo and directory names use hyphens (`x-bookmarks`, `gemini-notes`); connector Python packages keep underscores (`x_bookmarks`, `gemini_notes`).\n- **Page filenames:** standard wiki conventions (title-case, underscore, one file per entity).\n\n## Repository structure\n\n```\nmemory/\n README.md\n wiki/ # typed knowledge graph (living documents)\n raw/<source>/ # immutable captures, append-only (data)\n <capture-files> # unique per-item filenames\n raw/<source>/.cursor # monotonic opaque cursor (or .sync_token)\n raw/<source>/SUMMARY.json # run bookkeeping\n raw/<source>/thread_ids.json # per-source sidecar metadata (optional)\n connectors/<name>/ # connector code (centralized, not per-repo)\n queries/ # saved SPARQL queries\n wiki.yml # graph context, validation config\n .github/workflows/\n memory-check.yml # append-only + SUMMARY-schema invariant\n check.yml # wiki check + wiki fmt --check\n```\n\n`wiki/` pages are living documents. Everything under `raw/` is immutable and append-only; the only mutable files are the per-source metadata entries listed below.\n\n## Continuity contract\n\nA memory repo must be stable, unchanged, and replayable over time. It is the durable store that an ephemeral sandbox trusts — reproducibility is the property that makes host loss safe.\n\n1. **Append-only by construction.** Capture files use unique per-item or per-run filenames (timestamp- or source-ID-based) and are never overwritten. Re-cloning therefore never conflicts on `git pull`, because append-only files cannot collide.\n1. **No history surgery.** Never `force-push`, `reset`, or rewrite memory repo history. Enforce with branch protection: force-push and deletion disabled on `main`, administrator overrides off.\n1. **Monotonic cursor.** Cursors advance only forward. Replays are idempotent and never regress state.\n1. **Dedup by source identifier.** Every capture carries a source ID (`schema:identifier`); duplicate IDs within or across runs are skipped.\n1. **No TTL, no pruning.** Memory is the second-brain promise: nothing expires because of age. The repo is the memory, not a cache of it.\n1. **Run bookkeeping.** Each source keeps a `SUMMARY.json` that records the last run and its result; it doubles as the connector `status` output.\n1. **Stable derived pages.** Replaying identical source data leaves generated wiki pages untouched. Page-level run fields (`wazoo:source_run`, `wazoo:source_run_id`, and `wazoo:synced_at`) record the last run that changed the page and advance only when its source-derived content changes; source-wide run accounting stays in `raw/<source>/SUMMARY.json`.\n1. **Provenance, not copies.** Wiki pages reference captures through stable URLs or URIs (`raw:<source>/...` inside the repo, or `memory://<owner>/<source>/<path>` across repos) rather than inlining raw content.\n\n## Datasets per source\n\nEvery connector owns one dataset subtree, `raw/<source>/`, with:\n\n- **Immutable captures:** append-only files written once per item, named from the source identifier plus a readable slug (e.g. `raw/gmail/<message-id>-<slug>.md`).\n- **cursor:** an opaque, monotonic position marker the connector reads at fetch start and writes only after the run succeeds. Canonical cursor filenames are `.cursor` (default) and `.sync_token` (incremental sync connectors such as Calendar and Gmail).\n- **Mutable metadata whitelist:** `SUMMARY.json`, `.cursor`, `.sync_token`, `thread_ids.json`, and `.gitkeep` are the only mutable files under `raw/`; the memory-check invariant rejects any other modified, appended, or deleted path.\n- **SUMMARY.json** — the standardized bookkeeping contract:\n\n```json\n{\n \"status\": \"OK\",\n \"connector\": \"<source>\",\n \"fetched\": 42,\n \"ingested\": 5,\n \"skipped_by_appraisal\": 37,\n \"actionable_candidates\": 5,\n \"cursor\": \"opaque-cursor-value\",\n \"lastRun\": \"2026-08-27T06:00:00-07:00\"\n}\n```\n\nConnectors expose a shared CLI: `python -m connectors.<name> status`, `fetch`, and `process <file>`. The shared accounting (cursor, capture, dedup, summary, CLI) is provided by `ConnectorBase`; the per-connector extraction, appraisal, and capture formatting are the only unique code.\n\n## Connectivity and auth\n\nThe connector auth approach is intentionally **deferred (TBD)**: no third-party OAuth middleware (for example Nango or Composio) is prescribed. The preference is to hand-roll per-connector auth. Candidate mechanisms to evaluate before wiring each fetch:\n\n- Google family (calendar, gmail, drive): OAuth device flow with refresh tokens stored in the secrets vault (and cloud secrets for the agent runtime)\n- Signal: `signal-cli` on a persistent host\n- X bookmarks: local fixture\n\nCredentials never enter the repository; they live in the secrets vault and are injected by the orchestrator at run time.\n\n## Runtime and orchestration\n\nDaily automation runs as a scheduled GitHub Actions workflow (`connector-cron.yml`, daily 06:00 UTC), not a long-lived agent. Per run the workflow:\n\n1. Clones the memory repo fresh.\n1. Runs `python -m connectors.<source> fetch` for each scheduled source whose credentials are configured; a source with no credentials is **skipped, not failed** (each connector's fetch is gated on its secret being present).\n1. Captures and bookkeeping land in the same clone.\n1. Appraisal converts actionable captures into living records; the workflow generates and updates wiki pages from normalized data (a no-op until connectors emit appraised records).\n1. Gates: `wiki check` and `wiki fmt --check`, plus `scripts/memory_check.py --base origin/main` and the pytest suite.\n1. Commits one atomic change per run and pushes to `main` of the same repo; unchanged source-derived wiki pages are not rewritten solely to restamp the run's provenance. A run may still change `SUMMARY.json` or the cursor when recording the completed sync.\n\nHard gates are structurally enforced: validation runs before commit, and repository CI (`check.yml` + `memory-check.yml`) is the tripwire on push. Natural-language operators follow the atomic persistence protocol: one coherent transaction per commit, checkpoint commits when blocked, no destructive history operations without approval.\n\n## Escape hatch criteria\n\nSplit a source to `<product>-<source>-memory` only when the shared repo is genuinely constrained:\n\n- Raw volume or repository growth dominates the wiki's graph\n- A source needs separate access control (e.g. personal data permissions differ from the rest)\n- A source needs independent CI\n\nEach split is its own reviewable change: move the subtree, re-point provenance links, and re-run validation.\n\n## Roll-out\n\n- **Step 1 (this document):** conventions agreed.\n- **Step 2 — reference deployment (done):** the legacy personal wiki was renamed `EthanThatOneKid/ethanpedia` and archived; `EthanThatOneKid/memory` was re-created clean with the `raw/<source>/` per-source dataset scaffolding (fresh `SUMMARY.json` baselines, no legacy captures), `SUMMARY.json` + cursor conventions, branch protection, `check.yml` + `memory-check.yml` + `connector-cron.yml`, and the reference `ConnectorBase` + calendar scaffold. Tracked in [wazootech/wiki#261](https://github.com/wazootech/wiki/issues/261).\n- **Step 3 — Calendar reference connector:** wire `ConnectorBase` + Google Calendar end-to-end through fetch, bookkeeping, page generation, and the daily cron loop. Tracked in [memory#1](https://github.com/EthanThatOneKid/memory/issues/1). Legacy discussion lives in the archived tracker at [ethanpedia#45](https://github.com/EthanThatOneKid/ethanpedia/issues/45).\n- **Step 4 — replicate:** move each remaining connector onto the same pattern; stream-only provider imports stay gated on the [deferred imports ruling](https://github.com/EthanThatOneKid/ethanpedia/issues/28).\n\n## Cross-wiki identity\n\nWhen a raw capture keyed by `schema:identifier` later has to be matched to a curated page in another wiki, keep the generated record under its own filename and reconcile it with `owl:sameAs` on the curated page; a same-basename overlap is a `wiki check` error. See [Cross-Wiki Identity](Cross_Wiki_Identity.md).\n\n## Related\n\n- [Second Brain](Second_Brain.md) — the conceptual model a memory repo implements\n- [Personal Knowledge](Personal_Knowledge.md)\n- [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md) — composing git-backed wiki sources with named-graph provenance\n- [Letta MemFS](Letta_MemFS.md)",
"schema:dateCreated": {
"@type": "xsd:dateTime",
"@value": "2026-10-31T23:19:03Z"
},
"schema:dateModified": {
"@type": "xsd:dateTime",
"@value": "2026-10-31T23:19:03Z"
},
"schema:description": "The memory-first convention for per-owner wiki repositories — structure, naming, and continuity rules for durable, append-only second-brain repos managed with the wiki toolchain.",
"schema:headline": "Memory Repo Best Practices"
}
@prefix schema: <https://schema.org/>.
@prefix wiki: <https://wazootech.github.io/wiki/>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix dc: <http://purl.org/dc/elements/1.1/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix wazoo: <https://schema.wazoo.dev/>.
wiki:Memory_Repo_Best_Practices a schema:TechArticle;
schema:description "The memory-first convention for per-owner wiki repositories — structure, naming, and continuity rules for durable, append-only second-brain repos managed with the wiki toolchain.";
schema:articleBody "# Memory Repo Best Practices\n\nA **memory repo** is a per-owner wiki graph repository that is the durable store for one owner or organization's knowledge: typed wiki pages, per-source immutable datasets, connector code, and validation all live in one repository. This is the \"wiki repository memory-first\" model. This document is the spec that the [memory-first wiki repos issue](https://github.com/wazootech/wiki/issues/261) implements and that [connector memory wiring](https://github.com/EthanThatOneKid/ethanpedia/issues/45) builds against.\n\n## Model\n\nThe wiki repository _is_ the memory. There is no separate data tier: raw captures, normalized records, cursors, and bookkeeping live in the same repository as the knowledge graph, so the graph and its sources cannot drift.\n\n```\nEthanThatOneKid/\n .github/ # identity, meta, policies (uniform owner special repo)\n workspace/ # dev-surface harness (uniform owner special repo)\n memory/ # the memory wiki repo (uniform owner special repo)\n```\n\n## Naming\n\n- **Uniform per-owner name:** the memory repo is named `memory` under each owner or organization, joining `.github` and `workspace` as the third uniform owner special repo. Examples: `EthanThatOneKid/memory`, `wazootech/memory`.\n- **Role suffix:** the `-pedia` suffix previously designated knowledge repos (`ethanpedia`, `wazoopedia`). Going forward it describes the memory role: data repositories use the `memory` family, not `-pedia`. The `wazoopedia` repo has been renamed to `memory`.\n- **Per-source datasets are subtrees**, not repositories: `raw/<source>/` inside the memory repo.\n- **Escape hatch:** if a single source outgrows the shared repo (volume, access control, or CI isolation), split that subtree to a per-source repo named `<product>-<source>-memory` (e.g. `ethanpedia-calendar-memory`). Do not split preemptively.\n- **Transcription:** repo and directory names use hyphens (`x-bookmarks`, `gemini-notes`); connector Python packages keep underscores (`x_bookmarks`, `gemini_notes`).\n- **Page filenames:** standard wiki conventions (title-case, underscore, one file per entity).\n\n## Repository structure\n\n```\nmemory/\n README.md\n wiki/ # typed knowledge graph (living documents)\n raw/<source>/ # immutable captures, append-only (data)\n <capture-files> # unique per-item filenames\n raw/<source>/.cursor # monotonic opaque cursor (or .sync_token)\n raw/<source>/SUMMARY.json # run bookkeeping\n raw/<source>/thread_ids.json # per-source sidecar metadata (optional)\n connectors/<name>/ # connector code (centralized, not per-repo)\n queries/ # saved SPARQL queries\n wiki.yml # graph context, validation config\n .github/workflows/\n memory-check.yml # append-only + SUMMARY-schema invariant\n check.yml # wiki check + wiki fmt --check\n```\n\n`wiki/` pages are living documents. Everything under `raw/` is immutable and append-only; the only mutable files are the per-source metadata entries listed below.\n\n## Continuity contract\n\nA memory repo must be stable, unchanged, and replayable over time. It is the durable store that an ephemeral sandbox trusts — reproducibility is the property that makes host loss safe.\n\n1. **Append-only by construction.** Capture files use unique per-item or per-run filenames (timestamp- or source-ID-based) and are never overwritten. Re-cloning therefore never conflicts on `git pull`, because append-only files cannot collide.\n1. **No history surgery.** Never `force-push`, `reset`, or rewrite memory repo history. Enforce with branch protection: force-push and deletion disabled on `main`, administrator overrides off.\n1. **Monotonic cursor.** Cursors advance only forward. Replays are idempotent and never regress state.\n1. **Dedup by source identifier.** Every capture carries a source ID (`schema:identifier`); duplicate IDs within or across runs are skipped.\n1. **No TTL, no pruning.** Memory is the second-brain promise: nothing expires because of age. The repo is the memory, not a cache of it.\n1. **Run bookkeeping.** Each source keeps a `SUMMARY.json` that records the last run and its result; it doubles as the connector `status` output.\n1. **Stable derived pages.** Replaying identical source data leaves generated wiki pages untouched. Page-level run fields (`wazoo:source_run`, `wazoo:source_run_id`, and `wazoo:synced_at`) record the last run that changed the page and advance only when its source-derived content changes; source-wide run accounting stays in `raw/<source>/SUMMARY.json`.\n1. **Provenance, not copies.** Wiki pages reference captures through stable URLs or URIs (`raw:<source>/...` inside the repo, or `memory://<owner>/<source>/<path>` across repos) rather than inlining raw content.\n\n## Datasets per source\n\nEvery connector owns one dataset subtree, `raw/<source>/`, with:\n\n- **Immutable captures:** append-only files written once per item, named from the source identifier plus a readable slug (e.g. `raw/gmail/<message-id>-<slug>.md`).\n- **cursor:** an opaque, monotonic position marker the connector reads at fetch start and writes only after the run succeeds. Canonical cursor filenames are `.cursor` (default) and `.sync_token` (incremental sync connectors such as Calendar and Gmail).\n- **Mutable metadata whitelist:** `SUMMARY.json`, `.cursor`, `.sync_token`, `thread_ids.json`, and `.gitkeep` are the only mutable files under `raw/`; the memory-check invariant rejects any other modified, appended, or deleted path.\n- **SUMMARY.json** — the standardized bookkeeping contract:\n\n```json\n{\n \"status\": \"OK\",\n \"connector\": \"<source>\",\n \"fetched\": 42,\n \"ingested\": 5,\n \"skipped_by_appraisal\": 37,\n \"actionable_candidates\": 5,\n \"cursor\": \"opaque-cursor-value\",\n \"lastRun\": \"2026-08-27T06:00:00-07:00\"\n}\n```\n\nConnectors expose a shared CLI: `python -m connectors.<name> status`, `fetch`, and `process <file>`. The shared accounting (cursor, capture, dedup, summary, CLI) is provided by `ConnectorBase`; the per-connector extraction, appraisal, and capture formatting are the only unique code.\n\n## Connectivity and auth\n\nThe connector auth approach is intentionally **deferred (TBD)**: no third-party OAuth middleware (for example Nango or Composio) is prescribed. The preference is to hand-roll per-connector auth. Candidate mechanisms to evaluate before wiring each fetch:\n\n- Google family (calendar, gmail, drive): OAuth device flow with refresh tokens stored in the secrets vault (and cloud secrets for the agent runtime)\n- Signal: `signal-cli` on a persistent host\n- X bookmarks: local fixture\n\nCredentials never enter the repository; they live in the secrets vault and are injected by the orchestrator at run time.\n\n## Runtime and orchestration\n\nDaily automation runs as a scheduled GitHub Actions workflow (`connector-cron.yml`, daily 06:00 UTC), not a long-lived agent. Per run the workflow:\n\n1. Clones the memory repo fresh.\n1. Runs `python -m connectors.<source> fetch` for each scheduled source whose credentials are configured; a source with no credentials is **skipped, not failed** (each connector's fetch is gated on its secret being present).\n1. Captures and bookkeeping land in the same clone.\n1. Appraisal converts actionable captures into living records; the workflow generates and updates wiki pages from normalized data (a no-op until connectors emit appraised records).\n1. Gates: `wiki check` and `wiki fmt --check`, plus `scripts/memory_check.py --base origin/main` and the pytest suite.\n1. Commits one atomic change per run and pushes to `main` of the same repo; unchanged source-derived wiki pages are not rewritten solely to restamp the run's provenance. A run may still change `SUMMARY.json` or the cursor when recording the completed sync.\n\nHard gates are structurally enforced: validation runs before commit, and repository CI (`check.yml` + `memory-check.yml`) is the tripwire on push. Natural-language operators follow the atomic persistence protocol: one coherent transaction per commit, checkpoint commits when blocked, no destructive history operations without approval.\n\n## Escape hatch criteria\n\nSplit a source to `<product>-<source>-memory` only when the shared repo is genuinely constrained:\n\n- Raw volume or repository growth dominates the wiki's graph\n- A source needs separate access control (e.g. personal data permissions differ from the rest)\n- A source needs independent CI\n\nEach split is its own reviewable change: move the subtree, re-point provenance links, and re-run validation.\n\n## Roll-out\n\n- **Step 1 (this document):** conventions agreed.\n- **Step 2 — reference deployment (done):** the legacy personal wiki was renamed `EthanThatOneKid/ethanpedia` and archived; `EthanThatOneKid/memory` was re-created clean with the `raw/<source>/` per-source dataset scaffolding (fresh `SUMMARY.json` baselines, no legacy captures), `SUMMARY.json` + cursor conventions, branch protection, `check.yml` + `memory-check.yml` + `connector-cron.yml`, and the reference `ConnectorBase` + calendar scaffold. Tracked in [wazootech/wiki#261](https://github.com/wazootech/wiki/issues/261).\n- **Step 3 — Calendar reference connector:** wire `ConnectorBase` + Google Calendar end-to-end through fetch, bookkeeping, page generation, and the daily cron loop. Tracked in [memory#1](https://github.com/EthanThatOneKid/memory/issues/1). Legacy discussion lives in the archived tracker at [ethanpedia#45](https://github.com/EthanThatOneKid/ethanpedia/issues/45).\n- **Step 4 — replicate:** move each remaining connector onto the same pattern; stream-only provider imports stay gated on the [deferred imports ruling](https://github.com/EthanThatOneKid/ethanpedia/issues/28).\n\n## Cross-wiki identity\n\nWhen a raw capture keyed by `schema:identifier` later has to be matched to a curated page in another wiki, keep the generated record under its own filename and reconcile it with `owl:sameAs` on the curated page; a same-basename overlap is a `wiki check` error. See [Cross-Wiki Identity](Cross_Wiki_Identity.md).\n\n## Related\n\n- [Second Brain](Second_Brain.md) — the conceptual model a memory repo implements\n- [Personal Knowledge](Personal_Knowledge.md)\n- [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md) — composing git-backed wiki sources with named-graph provenance\n- [Letta MemFS](Letta_MemFS.md)";
schema:headline "Memory Repo Best Practices";
schema:dateCreated "2026-10-31T23:19:03Z"^^xsd:dateTime;
schema:dateModified "2026-10-31T23:19:03Z"^^xsd:dateTime.
@prefix schema: <https://schema.org/>.
@prefix wiki: <https://wazootech.github.io/wiki/>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix dc: <http://purl.org/dc/elements/1.1/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix wazoo: <https://schema.wazoo.dev/>.
wiki:Memory_Repo_Best_Practices a schema:TechArticle;
schema:description "The memory-first convention for per-owner wiki repositories — structure, naming, and continuity rules for durable, append-only second-brain repos managed with the wiki toolchain.";
schema:articleBody "# Memory Repo Best Practices\n\nA **memory repo** is a per-owner wiki graph repository that is the durable store for one owner or organization's knowledge: typed wiki pages, per-source immutable datasets, connector code, and validation all live in one repository. This is the \"wiki repository memory-first\" model. This document is the spec that the [memory-first wiki repos issue](https://github.com/wazootech/wiki/issues/261) implements and that [connector memory wiring](https://github.com/EthanThatOneKid/ethanpedia/issues/45) builds against.\n\n## Model\n\nThe wiki repository _is_ the memory. There is no separate data tier: raw captures, normalized records, cursors, and bookkeeping live in the same repository as the knowledge graph, so the graph and its sources cannot drift.\n\n```\nEthanThatOneKid/\n .github/ # identity, meta, policies (uniform owner special repo)\n workspace/ # dev-surface harness (uniform owner special repo)\n memory/ # the memory wiki repo (uniform owner special repo)\n```\n\n## Naming\n\n- **Uniform per-owner name:** the memory repo is named `memory` under each owner or organization, joining `.github` and `workspace` as the third uniform owner special repo. Examples: `EthanThatOneKid/memory`, `wazootech/memory`.\n- **Role suffix:** the `-pedia` suffix previously designated knowledge repos (`ethanpedia`, `wazoopedia`). Going forward it describes the memory role: data repositories use the `memory` family, not `-pedia`. The `wazoopedia` repo has been renamed to `memory`.\n- **Per-source datasets are subtrees**, not repositories: `raw/<source>/` inside the memory repo.\n- **Escape hatch:** if a single source outgrows the shared repo (volume, access control, or CI isolation), split that subtree to a per-source repo named `<product>-<source>-memory` (e.g. `ethanpedia-calendar-memory`). Do not split preemptively.\n- **Transcription:** repo and directory names use hyphens (`x-bookmarks`, `gemini-notes`); connector Python packages keep underscores (`x_bookmarks`, `gemini_notes`).\n- **Page filenames:** standard wiki conventions (title-case, underscore, one file per entity).\n\n## Repository structure\n\n```\nmemory/\n README.md\n wiki/ # typed knowledge graph (living documents)\n raw/<source>/ # immutable captures, append-only (data)\n <capture-files> # unique per-item filenames\n raw/<source>/.cursor # monotonic opaque cursor (or .sync_token)\n raw/<source>/SUMMARY.json # run bookkeeping\n raw/<source>/thread_ids.json # per-source sidecar metadata (optional)\n connectors/<name>/ # connector code (centralized, not per-repo)\n queries/ # saved SPARQL queries\n wiki.yml # graph context, validation config\n .github/workflows/\n memory-check.yml # append-only + SUMMARY-schema invariant\n check.yml # wiki check + wiki fmt --check\n```\n\n`wiki/` pages are living documents. Everything under `raw/` is immutable and append-only; the only mutable files are the per-source metadata entries listed below.\n\n## Continuity contract\n\nA memory repo must be stable, unchanged, and replayable over time. It is the durable store that an ephemeral sandbox trusts — reproducibility is the property that makes host loss safe.\n\n1. **Append-only by construction.** Capture files use unique per-item or per-run filenames (timestamp- or source-ID-based) and are never overwritten. Re-cloning therefore never conflicts on `git pull`, because append-only files cannot collide.\n1. **No history surgery.** Never `force-push`, `reset`, or rewrite memory repo history. Enforce with branch protection: force-push and deletion disabled on `main`, administrator overrides off.\n1. **Monotonic cursor.** Cursors advance only forward. Replays are idempotent and never regress state.\n1. **Dedup by source identifier.** Every capture carries a source ID (`schema:identifier`); duplicate IDs within or across runs are skipped.\n1. **No TTL, no pruning.** Memory is the second-brain promise: nothing expires because of age. The repo is the memory, not a cache of it.\n1. **Run bookkeeping.** Each source keeps a `SUMMARY.json` that records the last run and its result; it doubles as the connector `status` output.\n1. **Stable derived pages.** Replaying identical source data leaves generated wiki pages untouched. Page-level run fields (`wazoo:source_run`, `wazoo:source_run_id`, and `wazoo:synced_at`) record the last run that changed the page and advance only when its source-derived content changes; source-wide run accounting stays in `raw/<source>/SUMMARY.json`.\n1. **Provenance, not copies.** Wiki pages reference captures through stable URLs or URIs (`raw:<source>/...` inside the repo, or `memory://<owner>/<source>/<path>` across repos) rather than inlining raw content.\n\n## Datasets per source\n\nEvery connector owns one dataset subtree, `raw/<source>/`, with:\n\n- **Immutable captures:** append-only files written once per item, named from the source identifier plus a readable slug (e.g. `raw/gmail/<message-id>-<slug>.md`).\n- **cursor:** an opaque, monotonic position marker the connector reads at fetch start and writes only after the run succeeds. Canonical cursor filenames are `.cursor` (default) and `.sync_token` (incremental sync connectors such as Calendar and Gmail).\n- **Mutable metadata whitelist:** `SUMMARY.json`, `.cursor`, `.sync_token`, `thread_ids.json`, and `.gitkeep` are the only mutable files under `raw/`; the memory-check invariant rejects any other modified, appended, or deleted path.\n- **SUMMARY.json** — the standardized bookkeeping contract:\n\n```json\n{\n \"status\": \"OK\",\n \"connector\": \"<source>\",\n \"fetched\": 42,\n \"ingested\": 5,\n \"skipped_by_appraisal\": 37,\n \"actionable_candidates\": 5,\n \"cursor\": \"opaque-cursor-value\",\n \"lastRun\": \"2026-08-27T06:00:00-07:00\"\n}\n```\n\nConnectors expose a shared CLI: `python -m connectors.<name> status`, `fetch`, and `process <file>`. The shared accounting (cursor, capture, dedup, summary, CLI) is provided by `ConnectorBase`; the per-connector extraction, appraisal, and capture formatting are the only unique code.\n\n## Connectivity and auth\n\nThe connector auth approach is intentionally **deferred (TBD)**: no third-party OAuth middleware (for example Nango or Composio) is prescribed. The preference is to hand-roll per-connector auth. Candidate mechanisms to evaluate before wiring each fetch:\n\n- Google family (calendar, gmail, drive): OAuth device flow with refresh tokens stored in the secrets vault (and cloud secrets for the agent runtime)\n- Signal: `signal-cli` on a persistent host\n- X bookmarks: local fixture\n\nCredentials never enter the repository; they live in the secrets vault and are injected by the orchestrator at run time.\n\n## Runtime and orchestration\n\nDaily automation runs as a scheduled GitHub Actions workflow (`connector-cron.yml`, daily 06:00 UTC), not a long-lived agent. Per run the workflow:\n\n1. Clones the memory repo fresh.\n1. Runs `python -m connectors.<source> fetch` for each scheduled source whose credentials are configured; a source with no credentials is **skipped, not failed** (each connector's fetch is gated on its secret being present).\n1. Captures and bookkeeping land in the same clone.\n1. Appraisal converts actionable captures into living records; the workflow generates and updates wiki pages from normalized data (a no-op until connectors emit appraised records).\n1. Gates: `wiki check` and `wiki fmt --check`, plus `scripts/memory_check.py --base origin/main` and the pytest suite.\n1. Commits one atomic change per run and pushes to `main` of the same repo; unchanged source-derived wiki pages are not rewritten solely to restamp the run's provenance. A run may still change `SUMMARY.json` or the cursor when recording the completed sync.\n\nHard gates are structurally enforced: validation runs before commit, and repository CI (`check.yml` + `memory-check.yml`) is the tripwire on push. Natural-language operators follow the atomic persistence protocol: one coherent transaction per commit, checkpoint commits when blocked, no destructive history operations without approval.\n\n## Escape hatch criteria\n\nSplit a source to `<product>-<source>-memory` only when the shared repo is genuinely constrained:\n\n- Raw volume or repository growth dominates the wiki's graph\n- A source needs separate access control (e.g. personal data permissions differ from the rest)\n- A source needs independent CI\n\nEach split is its own reviewable change: move the subtree, re-point provenance links, and re-run validation.\n\n## Roll-out\n\n- **Step 1 (this document):** conventions agreed.\n- **Step 2 — reference deployment (done):** the legacy personal wiki was renamed `EthanThatOneKid/ethanpedia` and archived; `EthanThatOneKid/memory` was re-created clean with the `raw/<source>/` per-source dataset scaffolding (fresh `SUMMARY.json` baselines, no legacy captures), `SUMMARY.json` + cursor conventions, branch protection, `check.yml` + `memory-check.yml` + `connector-cron.yml`, and the reference `ConnectorBase` + calendar scaffold. Tracked in [wazootech/wiki#261](https://github.com/wazootech/wiki/issues/261).\n- **Step 3 — Calendar reference connector:** wire `ConnectorBase` + Google Calendar end-to-end through fetch, bookkeeping, page generation, and the daily cron loop. Tracked in [memory#1](https://github.com/EthanThatOneKid/memory/issues/1). Legacy discussion lives in the archived tracker at [ethanpedia#45](https://github.com/EthanThatOneKid/ethanpedia/issues/45).\n- **Step 4 — replicate:** move each remaining connector onto the same pattern; stream-only provider imports stay gated on the [deferred imports ruling](https://github.com/EthanThatOneKid/ethanpedia/issues/28).\n\n## Cross-wiki identity\n\nWhen a raw capture keyed by `schema:identifier` later has to be matched to a curated page in another wiki, keep the generated record under its own filename and reconcile it with `owl:sameAs` on the curated page; a same-basename overlap is a `wiki check` error. See [Cross-Wiki Identity](Cross_Wiki_Identity.md).\n\n## Related\n\n- [Second Brain](Second_Brain.md) — the conceptual model a memory repo implements\n- [Personal Knowledge](Personal_Knowledge.md)\n- [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md) — composing git-backed wiki sources with named-graph provenance\n- [Letta MemFS](Letta_MemFS.md)";
schema:headline "Memory Repo Best Practices";
schema:dateCreated "2026-10-31T23:19:03Z"^^xsd:dateTime;
schema:dateModified "2026-10-31T23:19:03Z"^^xsd:dateTime.
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://schema.org/TechArticle> .
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <https://schema.org/description> "The memory-first convention for per-owner wiki repositories — structure, naming, and continuity rules for durable, append-only second-brain repos managed with the wiki toolchain." .
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <https://schema.org/articleBody> "# Memory Repo Best Practices\n\nA **memory repo** is a per-owner wiki graph repository that is the durable store for one owner or organization's knowledge: typed wiki pages, per-source immutable datasets, connector code, and validation all live in one repository. This is the \"wiki repository memory-first\" model. This document is the spec that the [memory-first wiki repos issue](https://github.com/wazootech/wiki/issues/261) implements and that [connector memory wiring](https://github.com/EthanThatOneKid/ethanpedia/issues/45) builds against.\n\n## Model\n\nThe wiki repository _is_ the memory. There is no separate data tier: raw captures, normalized records, cursors, and bookkeeping live in the same repository as the knowledge graph, so the graph and its sources cannot drift.\n\n```\nEthanThatOneKid/\n .github/ # identity, meta, policies (uniform owner special repo)\n workspace/ # dev-surface harness (uniform owner special repo)\n memory/ # the memory wiki repo (uniform owner special repo)\n```\n\n## Naming\n\n- **Uniform per-owner name:** the memory repo is named `memory` under each owner or organization, joining `.github` and `workspace` as the third uniform owner special repo. Examples: `EthanThatOneKid/memory`, `wazootech/memory`.\n- **Role suffix:** the `-pedia` suffix previously designated knowledge repos (`ethanpedia`, `wazoopedia`). Going forward it describes the memory role: data repositories use the `memory` family, not `-pedia`. The `wazoopedia` repo has been renamed to `memory`.\n- **Per-source datasets are subtrees**, not repositories: `raw/<source>/` inside the memory repo.\n- **Escape hatch:** if a single source outgrows the shared repo (volume, access control, or CI isolation), split that subtree to a per-source repo named `<product>-<source>-memory` (e.g. `ethanpedia-calendar-memory`). Do not split preemptively.\n- **Transcription:** repo and directory names use hyphens (`x-bookmarks`, `gemini-notes`); connector Python packages keep underscores (`x_bookmarks`, `gemini_notes`).\n- **Page filenames:** standard wiki conventions (title-case, underscore, one file per entity).\n\n## Repository structure\n\n```\nmemory/\n README.md\n wiki/ # typed knowledge graph (living documents)\n raw/<source>/ # immutable captures, append-only (data)\n <capture-files> # unique per-item filenames\n raw/<source>/.cursor # monotonic opaque cursor (or .sync_token)\n raw/<source>/SUMMARY.json # run bookkeeping\n raw/<source>/thread_ids.json # per-source sidecar metadata (optional)\n connectors/<name>/ # connector code (centralized, not per-repo)\n queries/ # saved SPARQL queries\n wiki.yml # graph context, validation config\n .github/workflows/\n memory-check.yml # append-only + SUMMARY-schema invariant\n check.yml # wiki check + wiki fmt --check\n```\n\n`wiki/` pages are living documents. Everything under `raw/` is immutable and append-only; the only mutable files are the per-source metadata entries listed below.\n\n## Continuity contract\n\nA memory repo must be stable, unchanged, and replayable over time. It is the durable store that an ephemeral sandbox trusts — reproducibility is the property that makes host loss safe.\n\n1. **Append-only by construction.** Capture files use unique per-item or per-run filenames (timestamp- or source-ID-based) and are never overwritten. Re-cloning therefore never conflicts on `git pull`, because append-only files cannot collide.\n1. **No history surgery.** Never `force-push`, `reset`, or rewrite memory repo history. Enforce with branch protection: force-push and deletion disabled on `main`, administrator overrides off.\n1. **Monotonic cursor.** Cursors advance only forward. Replays are idempotent and never regress state.\n1. **Dedup by source identifier.** Every capture carries a source ID (`schema:identifier`); duplicate IDs within or across runs are skipped.\n1. **No TTL, no pruning.** Memory is the second-brain promise: nothing expires because of age. The repo is the memory, not a cache of it.\n1. **Run bookkeeping.** Each source keeps a `SUMMARY.json` that records the last run and its result; it doubles as the connector `status` output.\n1. **Stable derived pages.** Replaying identical source data leaves generated wiki pages untouched. Page-level run fields (`wazoo:source_run`, `wazoo:source_run_id`, and `wazoo:synced_at`) record the last run that changed the page and advance only when its source-derived content changes; source-wide run accounting stays in `raw/<source>/SUMMARY.json`.\n1. **Provenance, not copies.** Wiki pages reference captures through stable URLs or URIs (`raw:<source>/...` inside the repo, or `memory://<owner>/<source>/<path>` across repos) rather than inlining raw content.\n\n## Datasets per source\n\nEvery connector owns one dataset subtree, `raw/<source>/`, with:\n\n- **Immutable captures:** append-only files written once per item, named from the source identifier plus a readable slug (e.g. `raw/gmail/<message-id>-<slug>.md`).\n- **cursor:** an opaque, monotonic position marker the connector reads at fetch start and writes only after the run succeeds. Canonical cursor filenames are `.cursor` (default) and `.sync_token` (incremental sync connectors such as Calendar and Gmail).\n- **Mutable metadata whitelist:** `SUMMARY.json`, `.cursor`, `.sync_token`, `thread_ids.json`, and `.gitkeep` are the only mutable files under `raw/`; the memory-check invariant rejects any other modified, appended, or deleted path.\n- **SUMMARY.json** — the standardized bookkeeping contract:\n\n```json\n{\n \"status\": \"OK\",\n \"connector\": \"<source>\",\n \"fetched\": 42,\n \"ingested\": 5,\n \"skipped_by_appraisal\": 37,\n \"actionable_candidates\": 5,\n \"cursor\": \"opaque-cursor-value\",\n \"lastRun\": \"2026-08-27T06:00:00-07:00\"\n}\n```\n\nConnectors expose a shared CLI: `python -m connectors.<name> status`, `fetch`, and `process <file>`. The shared accounting (cursor, capture, dedup, summary, CLI) is provided by `ConnectorBase`; the per-connector extraction, appraisal, and capture formatting are the only unique code.\n\n## Connectivity and auth\n\nThe connector auth approach is intentionally **deferred (TBD)**: no third-party OAuth middleware (for example Nango or Composio) is prescribed. The preference is to hand-roll per-connector auth. Candidate mechanisms to evaluate before wiring each fetch:\n\n- Google family (calendar, gmail, drive): OAuth device flow with refresh tokens stored in the secrets vault (and cloud secrets for the agent runtime)\n- Signal: `signal-cli` on a persistent host\n- X bookmarks: local fixture\n\nCredentials never enter the repository; they live in the secrets vault and are injected by the orchestrator at run time.\n\n## Runtime and orchestration\n\nDaily automation runs as a scheduled GitHub Actions workflow (`connector-cron.yml`, daily 06:00 UTC), not a long-lived agent. Per run the workflow:\n\n1. Clones the memory repo fresh.\n1. Runs `python -m connectors.<source> fetch` for each scheduled source whose credentials are configured; a source with no credentials is **skipped, not failed** (each connector's fetch is gated on its secret being present).\n1. Captures and bookkeeping land in the same clone.\n1. Appraisal converts actionable captures into living records; the workflow generates and updates wiki pages from normalized data (a no-op until connectors emit appraised records).\n1. Gates: `wiki check` and `wiki fmt --check`, plus `scripts/memory_check.py --base origin/main` and the pytest suite.\n1. Commits one atomic change per run and pushes to `main` of the same repo; unchanged source-derived wiki pages are not rewritten solely to restamp the run's provenance. A run may still change `SUMMARY.json` or the cursor when recording the completed sync.\n\nHard gates are structurally enforced: validation runs before commit, and repository CI (`check.yml` + `memory-check.yml`) is the tripwire on push. Natural-language operators follow the atomic persistence protocol: one coherent transaction per commit, checkpoint commits when blocked, no destructive history operations without approval.\n\n## Escape hatch criteria\n\nSplit a source to `<product>-<source>-memory` only when the shared repo is genuinely constrained:\n\n- Raw volume or repository growth dominates the wiki's graph\n- A source needs separate access control (e.g. personal data permissions differ from the rest)\n- A source needs independent CI\n\nEach split is its own reviewable change: move the subtree, re-point provenance links, and re-run validation.\n\n## Roll-out\n\n- **Step 1 (this document):** conventions agreed.\n- **Step 2 — reference deployment (done):** the legacy personal wiki was renamed `EthanThatOneKid/ethanpedia` and archived; `EthanThatOneKid/memory` was re-created clean with the `raw/<source>/` per-source dataset scaffolding (fresh `SUMMARY.json` baselines, no legacy captures), `SUMMARY.json` + cursor conventions, branch protection, `check.yml` + `memory-check.yml` + `connector-cron.yml`, and the reference `ConnectorBase` + calendar scaffold. Tracked in [wazootech/wiki#261](https://github.com/wazootech/wiki/issues/261).\n- **Step 3 — Calendar reference connector:** wire `ConnectorBase` + Google Calendar end-to-end through fetch, bookkeeping, page generation, and the daily cron loop. Tracked in [memory#1](https://github.com/EthanThatOneKid/memory/issues/1). Legacy discussion lives in the archived tracker at [ethanpedia#45](https://github.com/EthanThatOneKid/ethanpedia/issues/45).\n- **Step 4 — replicate:** move each remaining connector onto the same pattern; stream-only provider imports stay gated on the [deferred imports ruling](https://github.com/EthanThatOneKid/ethanpedia/issues/28).\n\n## Cross-wiki identity\n\nWhen a raw capture keyed by `schema:identifier` later has to be matched to a curated page in another wiki, keep the generated record under its own filename and reconcile it with `owl:sameAs` on the curated page; a same-basename overlap is a `wiki check` error. See [Cross-Wiki Identity](Cross_Wiki_Identity.md).\n\n## Related\n\n- [Second Brain](Second_Brain.md) — the conceptual model a memory repo implements\n- [Personal Knowledge](Personal_Knowledge.md)\n- [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md) — composing git-backed wiki sources with named-graph provenance\n- [Letta MemFS](Letta_MemFS.md)" .
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <https://schema.org/headline> "Memory Repo Best Practices" .
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <https://schema.org/dateCreated> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <https://schema.org/dateModified> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
@prefix schema: <https://schema.org/>.
@prefix wiki: <https://wazootech.github.io/wiki/>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix dc: <http://purl.org/dc/elements/1.1/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix wazoo: <https://schema.wazoo.dev/>.
wiki:Memory_Repo_Best_Practices a schema:TechArticle;
schema:description "The memory-first convention for per-owner wiki repositories — structure, naming, and continuity rules for durable, append-only second-brain repos managed with the wiki toolchain.";
schema:articleBody "# Memory Repo Best Practices\n\nA **memory repo** is a per-owner wiki graph repository that is the durable store for one owner or organization's knowledge: typed wiki pages, per-source immutable datasets, connector code, and validation all live in one repository. This is the \"wiki repository memory-first\" model. This document is the spec that the [memory-first wiki repos issue](https://github.com/wazootech/wiki/issues/261) implements and that [connector memory wiring](https://github.com/EthanThatOneKid/ethanpedia/issues/45) builds against.\n\n## Model\n\nThe wiki repository _is_ the memory. There is no separate data tier: raw captures, normalized records, cursors, and bookkeeping live in the same repository as the knowledge graph, so the graph and its sources cannot drift.\n\n```\nEthanThatOneKid/\n .github/ # identity, meta, policies (uniform owner special repo)\n workspace/ # dev-surface harness (uniform owner special repo)\n memory/ # the memory wiki repo (uniform owner special repo)\n```\n\n## Naming\n\n- **Uniform per-owner name:** the memory repo is named `memory` under each owner or organization, joining `.github` and `workspace` as the third uniform owner special repo. Examples: `EthanThatOneKid/memory`, `wazootech/memory`.\n- **Role suffix:** the `-pedia` suffix previously designated knowledge repos (`ethanpedia`, `wazoopedia`). Going forward it describes the memory role: data repositories use the `memory` family, not `-pedia`. The `wazoopedia` repo has been renamed to `memory`.\n- **Per-source datasets are subtrees**, not repositories: `raw/<source>/` inside the memory repo.\n- **Escape hatch:** if a single source outgrows the shared repo (volume, access control, or CI isolation), split that subtree to a per-source repo named `<product>-<source>-memory` (e.g. `ethanpedia-calendar-memory`). Do not split preemptively.\n- **Transcription:** repo and directory names use hyphens (`x-bookmarks`, `gemini-notes`); connector Python packages keep underscores (`x_bookmarks`, `gemini_notes`).\n- **Page filenames:** standard wiki conventions (title-case, underscore, one file per entity).\n\n## Repository structure\n\n```\nmemory/\n README.md\n wiki/ # typed knowledge graph (living documents)\n raw/<source>/ # immutable captures, append-only (data)\n <capture-files> # unique per-item filenames\n raw/<source>/.cursor # monotonic opaque cursor (or .sync_token)\n raw/<source>/SUMMARY.json # run bookkeeping\n raw/<source>/thread_ids.json # per-source sidecar metadata (optional)\n connectors/<name>/ # connector code (centralized, not per-repo)\n queries/ # saved SPARQL queries\n wiki.yml # graph context, validation config\n .github/workflows/\n memory-check.yml # append-only + SUMMARY-schema invariant\n check.yml # wiki check + wiki fmt --check\n```\n\n`wiki/` pages are living documents. Everything under `raw/` is immutable and append-only; the only mutable files are the per-source metadata entries listed below.\n\n## Continuity contract\n\nA memory repo must be stable, unchanged, and replayable over time. It is the durable store that an ephemeral sandbox trusts — reproducibility is the property that makes host loss safe.\n\n1. **Append-only by construction.** Capture files use unique per-item or per-run filenames (timestamp- or source-ID-based) and are never overwritten. Re-cloning therefore never conflicts on `git pull`, because append-only files cannot collide.\n1. **No history surgery.** Never `force-push`, `reset`, or rewrite memory repo history. Enforce with branch protection: force-push and deletion disabled on `main`, administrator overrides off.\n1. **Monotonic cursor.** Cursors advance only forward. Replays are idempotent and never regress state.\n1. **Dedup by source identifier.** Every capture carries a source ID (`schema:identifier`); duplicate IDs within or across runs are skipped.\n1. **No TTL, no pruning.** Memory is the second-brain promise: nothing expires because of age. The repo is the memory, not a cache of it.\n1. **Run bookkeeping.** Each source keeps a `SUMMARY.json` that records the last run and its result; it doubles as the connector `status` output.\n1. **Stable derived pages.** Replaying identical source data leaves generated wiki pages untouched. Page-level run fields (`wazoo:source_run`, `wazoo:source_run_id`, and `wazoo:synced_at`) record the last run that changed the page and advance only when its source-derived content changes; source-wide run accounting stays in `raw/<source>/SUMMARY.json`.\n1. **Provenance, not copies.** Wiki pages reference captures through stable URLs or URIs (`raw:<source>/...` inside the repo, or `memory://<owner>/<source>/<path>` across repos) rather than inlining raw content.\n\n## Datasets per source\n\nEvery connector owns one dataset subtree, `raw/<source>/`, with:\n\n- **Immutable captures:** append-only files written once per item, named from the source identifier plus a readable slug (e.g. `raw/gmail/<message-id>-<slug>.md`).\n- **cursor:** an opaque, monotonic position marker the connector reads at fetch start and writes only after the run succeeds. Canonical cursor filenames are `.cursor` (default) and `.sync_token` (incremental sync connectors such as Calendar and Gmail).\n- **Mutable metadata whitelist:** `SUMMARY.json`, `.cursor`, `.sync_token`, `thread_ids.json`, and `.gitkeep` are the only mutable files under `raw/`; the memory-check invariant rejects any other modified, appended, or deleted path.\n- **SUMMARY.json** — the standardized bookkeeping contract:\n\n```json\n{\n \"status\": \"OK\",\n \"connector\": \"<source>\",\n \"fetched\": 42,\n \"ingested\": 5,\n \"skipped_by_appraisal\": 37,\n \"actionable_candidates\": 5,\n \"cursor\": \"opaque-cursor-value\",\n \"lastRun\": \"2026-08-27T06:00:00-07:00\"\n}\n```\n\nConnectors expose a shared CLI: `python -m connectors.<name> status`, `fetch`, and `process <file>`. The shared accounting (cursor, capture, dedup, summary, CLI) is provided by `ConnectorBase`; the per-connector extraction, appraisal, and capture formatting are the only unique code.\n\n## Connectivity and auth\n\nThe connector auth approach is intentionally **deferred (TBD)**: no third-party OAuth middleware (for example Nango or Composio) is prescribed. The preference is to hand-roll per-connector auth. Candidate mechanisms to evaluate before wiring each fetch:\n\n- Google family (calendar, gmail, drive): OAuth device flow with refresh tokens stored in the secrets vault (and cloud secrets for the agent runtime)\n- Signal: `signal-cli` on a persistent host\n- X bookmarks: local fixture\n\nCredentials never enter the repository; they live in the secrets vault and are injected by the orchestrator at run time.\n\n## Runtime and orchestration\n\nDaily automation runs as a scheduled GitHub Actions workflow (`connector-cron.yml`, daily 06:00 UTC), not a long-lived agent. Per run the workflow:\n\n1. Clones the memory repo fresh.\n1. Runs `python -m connectors.<source> fetch` for each scheduled source whose credentials are configured; a source with no credentials is **skipped, not failed** (each connector's fetch is gated on its secret being present).\n1. Captures and bookkeeping land in the same clone.\n1. Appraisal converts actionable captures into living records; the workflow generates and updates wiki pages from normalized data (a no-op until connectors emit appraised records).\n1. Gates: `wiki check` and `wiki fmt --check`, plus `scripts/memory_check.py --base origin/main` and the pytest suite.\n1. Commits one atomic change per run and pushes to `main` of the same repo; unchanged source-derived wiki pages are not rewritten solely to restamp the run's provenance. A run may still change `SUMMARY.json` or the cursor when recording the completed sync.\n\nHard gates are structurally enforced: validation runs before commit, and repository CI (`check.yml` + `memory-check.yml`) is the tripwire on push. Natural-language operators follow the atomic persistence protocol: one coherent transaction per commit, checkpoint commits when blocked, no destructive history operations without approval.\n\n## Escape hatch criteria\n\nSplit a source to `<product>-<source>-memory` only when the shared repo is genuinely constrained:\n\n- Raw volume or repository growth dominates the wiki's graph\n- A source needs separate access control (e.g. personal data permissions differ from the rest)\n- A source needs independent CI\n\nEach split is its own reviewable change: move the subtree, re-point provenance links, and re-run validation.\n\n## Roll-out\n\n- **Step 1 (this document):** conventions agreed.\n- **Step 2 — reference deployment (done):** the legacy personal wiki was renamed `EthanThatOneKid/ethanpedia` and archived; `EthanThatOneKid/memory` was re-created clean with the `raw/<source>/` per-source dataset scaffolding (fresh `SUMMARY.json` baselines, no legacy captures), `SUMMARY.json` + cursor conventions, branch protection, `check.yml` + `memory-check.yml` + `connector-cron.yml`, and the reference `ConnectorBase` + calendar scaffold. Tracked in [wazootech/wiki#261](https://github.com/wazootech/wiki/issues/261).\n- **Step 3 — Calendar reference connector:** wire `ConnectorBase` + Google Calendar end-to-end through fetch, bookkeeping, page generation, and the daily cron loop. Tracked in [memory#1](https://github.com/EthanThatOneKid/memory/issues/1). Legacy discussion lives in the archived tracker at [ethanpedia#45](https://github.com/EthanThatOneKid/ethanpedia/issues/45).\n- **Step 4 — replicate:** move each remaining connector onto the same pattern; stream-only provider imports stay gated on the [deferred imports ruling](https://github.com/EthanThatOneKid/ethanpedia/issues/28).\n\n## Cross-wiki identity\n\nWhen a raw capture keyed by `schema:identifier` later has to be matched to a curated page in another wiki, keep the generated record under its own filename and reconcile it with `owl:sameAs` on the curated page; a same-basename overlap is a `wiki check` error. See [Cross-Wiki Identity](Cross_Wiki_Identity.md).\n\n## Related\n\n- [Second Brain](Second_Brain.md) — the conceptual model a memory repo implements\n- [Personal Knowledge](Personal_Knowledge.md)\n- [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md) — composing git-backed wiki sources with named-graph provenance\n- [Letta MemFS](Letta_MemFS.md)";
schema:headline "Memory Repo Best Practices";
schema:dateCreated "2026-10-31T23:19:03Z"^^xsd:dateTime;
schema:dateModified "2026-10-31T23:19:03Z"^^xsd:dateTime.
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://schema.org/TechArticle> .
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <https://schema.org/description> "The memory-first convention for per-owner wiki repositories — structure, naming, and continuity rules for durable, append-only second-brain repos managed with the wiki toolchain." .
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <https://schema.org/articleBody> """# Memory Repo Best Practices
A **memory repo** is a per-owner wiki graph repository that is the durable store for one owner or organization's knowledge: typed wiki pages, per-source immutable datasets, connector code, and validation all live in one repository. This is the "wiki repository memory-first" model. This document is the spec that the [memory-first wiki repos issue](https://github.com/wazootech/wiki/issues/261) implements and that [connector memory wiring](https://github.com/EthanThatOneKid/ethanpedia/issues/45) builds against.
## Model
The wiki repository _is_ the memory. There is no separate data tier: raw captures, normalized records, cursors, and bookkeeping live in the same repository as the knowledge graph, so the graph and its sources cannot drift.
```
EthanThatOneKid/
.github/ # identity, meta, policies (uniform owner special repo)
workspace/ # dev-surface harness (uniform owner special repo)
memory/ # the memory wiki repo (uniform owner special repo)
```
## Naming
- **Uniform per-owner name:** the memory repo is named `memory` under each owner or organization, joining `.github` and `workspace` as the third uniform owner special repo. Examples: `EthanThatOneKid/memory`, `wazootech/memory`.
- **Role suffix:** the `-pedia` suffix previously designated knowledge repos (`ethanpedia`, `wazoopedia`). Going forward it describes the memory role: data repositories use the `memory` family, not `-pedia`. The `wazoopedia` repo has been renamed to `memory`.
- **Per-source datasets are subtrees**, not repositories: `raw/<source>/` inside the memory repo.
- **Escape hatch:** if a single source outgrows the shared repo (volume, access control, or CI isolation), split that subtree to a per-source repo named `<product>-<source>-memory` (e.g. `ethanpedia-calendar-memory`). Do not split preemptively.
- **Transcription:** repo and directory names use hyphens (`x-bookmarks`, `gemini-notes`); connector Python packages keep underscores (`x_bookmarks`, `gemini_notes`).
- **Page filenames:** standard wiki conventions (title-case, underscore, one file per entity).
## Repository structure
```
memory/
README.md
wiki/ # typed knowledge graph (living documents)
raw/<source>/ # immutable captures, append-only (data)
<capture-files> # unique per-item filenames
raw/<source>/.cursor # monotonic opaque cursor (or .sync_token)
raw/<source>/SUMMARY.json # run bookkeeping
raw/<source>/thread_ids.json # per-source sidecar metadata (optional)
connectors/<name>/ # connector code (centralized, not per-repo)
queries/ # saved SPARQL queries
wiki.yml # graph context, validation config
.github/workflows/
memory-check.yml # append-only + SUMMARY-schema invariant
check.yml # wiki check + wiki fmt --check
```
`wiki/` pages are living documents. Everything under `raw/` is immutable and append-only; the only mutable files are the per-source metadata entries listed below.
## Continuity contract
A memory repo must be stable, unchanged, and replayable over time. It is the durable store that an ephemeral sandbox trusts — reproducibility is the property that makes host loss safe.
1. **Append-only by construction.** Capture files use unique per-item or per-run filenames (timestamp- or source-ID-based) and are never overwritten. Re-cloning therefore never conflicts on `git pull`, because append-only files cannot collide.
1. **No history surgery.** Never `force-push`, `reset`, or rewrite memory repo history. Enforce with branch protection: force-push and deletion disabled on `main`, administrator overrides off.
1. **Monotonic cursor.** Cursors advance only forward. Replays are idempotent and never regress state.
1. **Dedup by source identifier.** Every capture carries a source ID (`schema:identifier`); duplicate IDs within or across runs are skipped.
1. **No TTL, no pruning.** Memory is the second-brain promise: nothing expires because of age. The repo is the memory, not a cache of it.
1. **Run bookkeeping.** Each source keeps a `SUMMARY.json` that records the last run and its result; it doubles as the connector `status` output.
1. **Stable derived pages.** Replaying identical source data leaves generated wiki pages untouched. Page-level run fields (`wazoo:source_run`, `wazoo:source_run_id`, and `wazoo:synced_at`) record the last run that changed the page and advance only when its source-derived content changes; source-wide run accounting stays in `raw/<source>/SUMMARY.json`.
1. **Provenance, not copies.** Wiki pages reference captures through stable URLs or URIs (`raw:<source>/...` inside the repo, or `memory://<owner>/<source>/<path>` across repos) rather than inlining raw content.
## Datasets per source
Every connector owns one dataset subtree, `raw/<source>/`, with:
- **Immutable captures:** append-only files written once per item, named from the source identifier plus a readable slug (e.g. `raw/gmail/<message-id>-<slug>.md`).
- **cursor:** an opaque, monotonic position marker the connector reads at fetch start and writes only after the run succeeds. Canonical cursor filenames are `.cursor` (default) and `.sync_token` (incremental sync connectors such as Calendar and Gmail).
- **Mutable metadata whitelist:** `SUMMARY.json`, `.cursor`, `.sync_token`, `thread_ids.json`, and `.gitkeep` are the only mutable files under `raw/`; the memory-check invariant rejects any other modified, appended, or deleted path.
- **SUMMARY.json** — the standardized bookkeeping contract:
```json
{
"status": "OK",
"connector": "<source>",
"fetched": 42,
"ingested": 5,
"skipped_by_appraisal": 37,
"actionable_candidates": 5,
"cursor": "opaque-cursor-value",
"lastRun": "2026-08-27T06:00:00-07:00"
}
```
Connectors expose a shared CLI: `python -m connectors.<name> status`, `fetch`, and `process <file>`. The shared accounting (cursor, capture, dedup, summary, CLI) is provided by `ConnectorBase`; the per-connector extraction, appraisal, and capture formatting are the only unique code.
## Connectivity and auth
The connector auth approach is intentionally **deferred (TBD)**: no third-party OAuth middleware (for example Nango or Composio) is prescribed. The preference is to hand-roll per-connector auth. Candidate mechanisms to evaluate before wiring each fetch:
- Google family (calendar, gmail, drive): OAuth device flow with refresh tokens stored in the secrets vault (and cloud secrets for the agent runtime)
- Signal: `signal-cli` on a persistent host
- X bookmarks: local fixture
Credentials never enter the repository; they live in the secrets vault and are injected by the orchestrator at run time.
## Runtime and orchestration
Daily automation runs as a scheduled GitHub Actions workflow (`connector-cron.yml`, daily 06:00 UTC), not a long-lived agent. Per run the workflow:
1. Clones the memory repo fresh.
1. Runs `python -m connectors.<source> fetch` for each scheduled source whose credentials are configured; a source with no credentials is **skipped, not failed** (each connector's fetch is gated on its secret being present).
1. Captures and bookkeeping land in the same clone.
1. Appraisal converts actionable captures into living records; the workflow generates and updates wiki pages from normalized data (a no-op until connectors emit appraised records).
1. Gates: `wiki check` and `wiki fmt --check`, plus `scripts/memory_check.py --base origin/main` and the pytest suite.
1. Commits one atomic change per run and pushes to `main` of the same repo; unchanged source-derived wiki pages are not rewritten solely to restamp the run's provenance. A run may still change `SUMMARY.json` or the cursor when recording the completed sync.
Hard gates are structurally enforced: validation runs before commit, and repository CI (`check.yml` + `memory-check.yml`) is the tripwire on push. Natural-language operators follow the atomic persistence protocol: one coherent transaction per commit, checkpoint commits when blocked, no destructive history operations without approval.
## Escape hatch criteria
Split a source to `<product>-<source>-memory` only when the shared repo is genuinely constrained:
- Raw volume or repository growth dominates the wiki's graph
- A source needs separate access control (e.g. personal data permissions differ from the rest)
- A source needs independent CI
Each split is its own reviewable change: move the subtree, re-point provenance links, and re-run validation.
## Roll-out
- **Step 1 (this document):** conventions agreed.
- **Step 2 — reference deployment (done):** the legacy personal wiki was renamed `EthanThatOneKid/ethanpedia` and archived; `EthanThatOneKid/memory` was re-created clean with the `raw/<source>/` per-source dataset scaffolding (fresh `SUMMARY.json` baselines, no legacy captures), `SUMMARY.json` + cursor conventions, branch protection, `check.yml` + `memory-check.yml` + `connector-cron.yml`, and the reference `ConnectorBase` + calendar scaffold. Tracked in [wazootech/wiki#261](https://github.com/wazootech/wiki/issues/261).
- **Step 3 — Calendar reference connector:** wire `ConnectorBase` + Google Calendar end-to-end through fetch, bookkeeping, page generation, and the daily cron loop. Tracked in [memory#1](https://github.com/EthanThatOneKid/memory/issues/1). Legacy discussion lives in the archived tracker at [ethanpedia#45](https://github.com/EthanThatOneKid/ethanpedia/issues/45).
- **Step 4 — replicate:** move each remaining connector onto the same pattern; stream-only provider imports stay gated on the [deferred imports ruling](https://github.com/EthanThatOneKid/ethanpedia/issues/28).
## Cross-wiki identity
When a raw capture keyed by `schema:identifier` later has to be matched to a curated page in another wiki, keep the generated record under its own filename and reconcile it with `owl:sameAs` on the curated page; a same-basename overlap is a `wiki check` error. See [Cross-Wiki Identity](Cross_Wiki_Identity.md).
## Related
- [Second Brain](Second_Brain.md) — the conceptual model a memory repo implements
- [Personal Knowledge](Personal_Knowledge.md)
- [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md) — composing git-backed wiki sources with named-graph provenance
- [Letta MemFS](Letta_MemFS.md)""" .
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <https://schema.org/headline> "Memory Repo Best Practices" .
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <https://schema.org/dateCreated> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<https://wazootech.github.io/wiki/Memory_Repo_Best_Practices> <https://schema.org/dateModified> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .