From 7a02b2f4ec4d20cb1142775a1debbc9a81645b93 Mon Sep 17 00:00:00 2001 From: Carlos Mora Date: Sat, 23 May 2026 10:36:48 -0500 Subject: [PATCH 1/2] docs: add team usage guide Adds docs/TEAM-USAGE.md covering the scope mental model (project vs personal), the lingua franca convention for shared memory, and the sync behavior teams actually get today. Honest about the current contract: scope filters search and context reads but does not filter sync. Both scopes leave the machine when the project is enrolled. Documents two workarounds (separate project name or no enrollment) and flags scope-aware sync as a deliberate future design decision. Linked from DOCS.md, the README nav, and the mem_save scope parameter description so the guide is discoverable from the obvious entry points. Closes #305 --- DOCS.md | 3 +- README.md | 1 + docs/TEAM-USAGE.md | 125 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 docs/TEAM-USAGE.md diff --git a/DOCS.md b/DOCS.md index cbcbe3d4..4ddf7d5e 100644 --- a/DOCS.md +++ b/DOCS.md @@ -33,6 +33,7 @@ For other docs: | [Codebase Guide](docs/CODEBASE-GUIDE.md) | Definitive guide to repository structure, package ownership, flows, and maintainer guardrails | | [Architecture](docs/ARCHITECTURE.md) | How it works, session lifecycle, CLI reference, project structure | | [Plugins](docs/PLUGINS.md) | OpenCode & Claude Code plugin details | +| [Team Usage](docs/TEAM-USAGE.md) | Scope conventions, language strategy, and sync behavior for collaborative teams | | [Comparison](docs/COMPARISON.md) | Why Engram vs claude-mem | --- @@ -779,7 +780,7 @@ Save structured observations. The tool description teaches agents the format: - **title**: Short, searchable (e.g. "JWT auth middleware") - **type**: `decision` | `architecture` | `bugfix` | `pattern` | `config` | `discovery` | `learning` -- **scope**: `project` (default) | `personal` +- **scope**: `project` (default) | `personal` — see [Team Usage](docs/TEAM-USAGE.md) for conventions and sync caveats - **topic_key**: optional canonical topic id (e.g. `architecture/auth-model`) used to upsert evolving memories - **capture_prompt**: optional boolean, default `true`; when current prompt context is available in the same MCP process for the same project/session, Engram best-effort records it alongside the observation. If that process-local context is unavailable or prompt capture fails, `mem_save` still succeeds. Automated pipeline saves such as SDD artifacts should pass `false`. - **content**: Structured with `**What**`, `**Why**`, `**Where**`, `**Learned**`; required unless the legacy `observation` alias is provided diff --git a/README.md b/README.md index 5727012b..213e637a 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Codebase Guide • Architecture • Plugins • + Team Usage • Contributing • Full Docs

diff --git a/docs/TEAM-USAGE.md b/docs/TEAM-USAGE.md new file mode 100644 index 00000000..a9589b10 --- /dev/null +++ b/docs/TEAM-USAGE.md @@ -0,0 +1,125 @@ +# Team Usage Guide + +This guide is for teams adopting Engram collaboratively. It explains what `scope: project` and `scope: personal` mean in practice, what language to use for shared memory, and how scope interacts with sync today. + +If you are an individual developer using Engram, you can stick to defaults and skip this page. + +--- + +## Mental model: project vs personal scope + +Every observation Engram saves has a scope. The two values are: + +- **`scope: project`** (default) — memory about the project itself: decisions, bugfixes, conventions, gotchas. Intended to be useful to other teammates and to their AI agents. +- **`scope: personal`** — memory that only matters to you: reading notes, personal shortcuts, style preferences, learning links. + +The quick rule of thumb: + +> If a teammate's AI agent should find this memory, save it as `project`. If it's only useful to you, save it as `personal`. + +### What scope actually does today + +Scope is a **search and filter signal**, not a privacy boundary. Concretely: + +- `mem_search`, `mem_context`, `GET /search`, and `GET /context` accept a `scope` parameter and filter results accordingly. +- The MCP `mem_save` and the REST `POST /observations` endpoints persist the scope value alongside the observation. +- Agents reading the memory base can choose to focus on shared knowledge (`scope: project`) or your personal workspace (`scope: personal`). + +### What scope does NOT do today + +Scope **does not filter sync**. When a project is enrolled for cloud sync (or when you run `engram sync` locally), both `project` and `personal` observations of that project are exported and shared with whoever has access to the sync target. + +If you need true isolation for personal notes, two workarounds work today: + +1. **Use a separate project name for personal notes** (e.g. `myname-notes`) and do not enroll that project for cloud sync. +2. **Do not enroll the shared project** if you save personal observations there. + +A future change may add scope-aware sync filtering. Until then, treat scope as a semantic and search convention, not a transport-level guarantee. + +--- + +## What to save in each scope + +| Save as `scope: project` | Save as `scope: personal` | +|--------------------------|---------------------------| +| Architectural decisions and tradeoffs | Personal reading notes and learnings | +| Bugfixes that affect other contributors | Editor shortcuts and dotfile tweaks | +| Conventions, naming rules, repo gotchas | Style or workflow preferences | +| API contracts, deployment quirks | Links to articles you want to revisit | +| Onboarding context for new contributors | Personal todos and reminders | + +### Examples + +**Project scope** (shared with the team): + +``` +title: "JWT refresh token rotation" +type: decision +scope: project +content: **What**: Rotate refresh tokens on every use, invalidate the +old one immediately. **Why**: prevents replay attacks if a token leaks +in transit. **Where**: src/auth/refresh.ts. +``` + +**Personal scope** (your own workspace): + +``` +title: "Postgres EXPLAIN cheatsheet" +type: learning +scope: personal +content: **What**: Quick reference for reading EXPLAIN output. +**Learned**: Sequential scans on a 10k row table are usually fine; +worry when you see them on tables with >100k rows. +``` + +--- + +## Language strategy for shared memory + +FTS5, the SQLite full-text search engine Engram uses, is language-agnostic but not multilingual. A search in English will not match an observation saved in Spanish, and vice versa. For a globally distributed team, this matters: if every developer saves project-scope memories in their native language, the shared knowledge base fragments and search stops working as a team tool. + +### Convention + +- **`scope: project`** → save in the team's lingua franca. For most international teams this is English, matching code, commits, and PRs. +- **`scope: personal`** → save in any language you prefer. Nobody else searches your personal scope, so language drift has no cost. + +### Why this matters + +Picture a project with English, Spanish, Russian, and Japanese speakers. Without a language convention, a developer searches `auth middleware decision` and only finds the entries an English-speaking teammate saved. The Russian developer's equally valuable note titled `решение по auth middleware` stays invisible. The shared knowledge base fragments along language lines. + +Picking one language for shared memory keeps the search index coherent. Personal scope stays free for whatever language helps you think. + +--- + +## Adopting these conventions on a team + +The mechanics are already in place; what teams need is a written agreement. Three concrete steps: + +1. **Document the conventions in your project README.** A short section that says "we save shared memory in English under `scope: project`; personal notes go under `scope: personal`" is enough to align everyone. +2. **Mention scope in code review.** When a memory-related change lands, check whether the saved observations chose the right scope. A misplaced `scope: personal` for a decision that should be team-visible erodes the shared knowledge base over time. +3. **Audit regularly with `mem_context`.** Run `mem_context` with `scope: personal` once in a while to make sure nothing team-relevant slipped into your personal workspace, and vice versa. + +--- + +## Sync behavior today (read this if you collaborate) + +Two flows move observations off your machine: + +- **Engram Cloud autosync.** When a project is enrolled and autosync is enabled, mutations push to the cloud server. See [`docs/AGENT-SETUP.md`](AGENT-SETUP.md#cloud-autosync-toggle) for the toggle. +- **Local `engram sync`.** Exports project-scoped chunks to `.engram/` for sharing via git or any file-based transport. + +Both flows export observations of the target project regardless of their scope. `personal` does not stay local automatically. The recommended pattern today: + +- **Shared work** → use a project name everyone on the team uses; enroll it for cloud sync. Save shared knowledge as `scope: project` in the team lingua franca. +- **Truly personal notes** → either (a) save them under a separate project name that you do not enroll, or (b) keep them off Engram entirely. + +If your team needs scope-aware sync (personal observations stay on your machine, project observations sync to the team), open an issue describing the policy you want and the data flow you expect. The current contract is "enrolled project means full project export"; changing that needs a deliberate design decision. + +--- + +## Related docs + +- [`docs/AGENT-SETUP.md`](AGENT-SETUP.md) — per-agent setup, Memory Protocol, autosync toggle. +- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) — session lifecycle, topic keys, memory hygiene. +- [`docs/engram-cloud/README.md`](engram-cloud/README.md) — Engram Cloud overview and enrollment. +- [`DOCS.md`](../DOCS.md) — full reference for tools, endpoints, and storage. From 241f23f102fba092d759d7e4b69c007f6b88ff0d Mon Sep 17 00:00:00 2001 From: Alan Buscaglia Date: Fri, 29 May 2026 14:20:14 +0200 Subject: [PATCH 2/2] docs(team-usage): clarify sync operates by project/session association per #331 review --- docs/TEAM-USAGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TEAM-USAGE.md b/docs/TEAM-USAGE.md index a9589b10..03330689 100644 --- a/docs/TEAM-USAGE.md +++ b/docs/TEAM-USAGE.md @@ -27,7 +27,7 @@ Scope is a **search and filter signal**, not a privacy boundary. Concretely: ### What scope does NOT do today -Scope **does not filter sync**. When a project is enrolled for cloud sync (or when you run `engram sync` locally), both `project` and `personal` observations of that project are exported and shared with whoever has access to the sync target. +Scope **does not filter sync**. Sync operates by **project/session association**, not by scope: when a project is enrolled for cloud sync (or when you run `engram sync` locally), both `project` and `personal` observations of that project are exported and shared with whoever has access to the sync target. If you need true isolation for personal notes, two workarounds work today: