docs: hosted memory governance contract design (#6)#48
Merged
Conversation
Proposes the coven-github <-> coven-code memory contract: a deny-by-default memory_policy brief block (tenant/repo/branch/trust scoping, read/write scopes, approval, retention), memory_used result metadata for citation and validation, a trust model where fork/external actors can never write durable memory, prefix-addressable keys for inspect/revoke, redaction of secrets before persistence, and adapter-side re-validation of every memory write. Phased for coordinated bilateral rollout. Signed-off-by: Val Alexander <bunsthedev@gmail.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new design/contract document defining how hosted durable memory governance should be expressed and enforced across the coven-github (policy authority) → coven-code (policy enforcer) boundary, as groundwork for issue #6 and related hosted-safety work.
Changes:
- Introduces a proposed
memory_policyblock forsession-brief.jsonto explicitly scope memory enablement, read/write namespaces, trust, and retention. - Specifies
memory_usedresult metadata to support citation, approval workflows, and adapter-side revalidation of proposed writes. - Documents the trust model, key addressability requirements, and redaction/enforcement points in the adapter.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+60
to
+61
| - Local/self-hosted memory behavior. Self-hosters own their own store; the | ||
| fail-closed hosted rules apply only when a `memory_policy` is present. |
Comment on lines
+156
to
+161
| - **`read_scopes` / `write_scopes`** name namespaces, never raw paths. The | ||
| runtime resolves a namespace to concrete keys itself, but every resolved key | ||
| MUST be prefixed by the tenant + repo coordinates (see | ||
| [Addressability](#addressability-inspect-and-revoke)). `tenant_shared` is | ||
| cross-repo memory *within one installation*; `familiar_global` is | ||
| cross-tenant and is **never** granted in hosted mode by default. |
Comment on lines
+170
to
+173
| | `trust_scope` | Who | Default read | Default durable write | | ||
| |---|---|---|---| | ||
| | `maintainer` | admin/maintain/write actor on the target repo (see #13 permission gate) | `repo`, `tenant_shared` | `repo` (subject to `approval_required`) | | ||
| | `collaborator` | triage/read collaborator | `repo` | none (may *propose*, needs approval) | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design/contract doc for #6, following the repo's established pattern (a design doc —
docs/durable-task-store.md— precedes the coordinated implementation). Single new file, no code touched, so it doesn't contend with the in-flight #2 store work or the #13 permission-gate follow-up.What it defines
docs/memory-contract.md— the memory governance contract betweencoven-github(policy authority) andcoven-code(policy enforcer):memory_policybrief block (additive, optional, deny-by-default): tenant/repo/branch scope, atrust_scopeenum,read_scopes/write_scopesnamespaces,approval_required, andretention. Absent block or missing scope = memory off, never "unrestricted".memory_usedresult metadata: entries read (for citation), proposed writes (with approval state), and runtime-rejected candidates — so the adapter can re-validate and reviews can cite what memory shaped them.repo/<owner>/<name>/...,tenant/<install>/...) that make inspect/revoke-by-installation/repo mechanically possible (the API surface itself waits on Add tenant-scoped task API authentication for CovenCave and hosted clients #3).@familiar remember/forgetcommands will drive.Scope
Design only — it proposes the additive schema changes (
session-brief.schema.json,result.schema.json) but does not edit the locked bilateral contract, since those land in lockstep with the coven-code side. Phased for coordinated rollout; does not close #6.Relationship to sibling issues is called out inline: builds toward #3 (inspect/revoke API), reuses #13's permission lookup for
trust_scope, and reuses #4'sredactmodule.🤖 Generated with Claude Code