|
| 1 | +# Team Usage Guide |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +If you are an individual developer using Engram, you can stick to defaults and skip this page. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## Mental model: project vs personal scope |
| 10 | + |
| 11 | +Every observation Engram saves has a scope. The two values are: |
| 12 | + |
| 13 | +- **`scope: project`** (default) — memory about the project itself: decisions, bugfixes, conventions, gotchas. Intended to be useful to other teammates and to their AI agents. |
| 14 | +- **`scope: personal`** — memory that only matters to you: reading notes, personal shortcuts, style preferences, learning links. |
| 15 | + |
| 16 | +The quick rule of thumb: |
| 17 | + |
| 18 | +> 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`. |
| 19 | +
|
| 20 | +### What scope actually does today |
| 21 | + |
| 22 | +Scope is a **search and filter signal**, not a privacy boundary. Concretely: |
| 23 | + |
| 24 | +- `mem_search`, `mem_context`, `GET /search`, and `GET /context` accept a `scope` parameter and filter results accordingly. |
| 25 | +- The MCP `mem_save` and the REST `POST /observations` endpoints persist the scope value alongside the observation. |
| 26 | +- Agents reading the memory base can choose to focus on shared knowledge (`scope: project`) or your personal workspace (`scope: personal`). |
| 27 | + |
| 28 | +### What scope does NOT do today |
| 29 | + |
| 30 | +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. |
| 31 | + |
| 32 | +If you need true isolation for personal notes, two workarounds work today: |
| 33 | + |
| 34 | +1. **Use a separate project name for personal notes** (e.g. `myname-notes`) and do not enroll that project for cloud sync. |
| 35 | +2. **Do not enroll the shared project** if you save personal observations there. |
| 36 | + |
| 37 | +A future change may add scope-aware sync filtering. Until then, treat scope as a semantic and search convention, not a transport-level guarantee. |
| 38 | + |
| 39 | +--- |
| 40 | + |
| 41 | +## What to save in each scope |
| 42 | + |
| 43 | +| Save as `scope: project` | Save as `scope: personal` | |
| 44 | +|--------------------------|---------------------------| |
| 45 | +| Architectural decisions and tradeoffs | Personal reading notes and learnings | |
| 46 | +| Bugfixes that affect other contributors | Editor shortcuts and dotfile tweaks | |
| 47 | +| Conventions, naming rules, repo gotchas | Style or workflow preferences | |
| 48 | +| API contracts, deployment quirks | Links to articles you want to revisit | |
| 49 | +| Onboarding context for new contributors | Personal todos and reminders | |
| 50 | + |
| 51 | +### Examples |
| 52 | + |
| 53 | +**Project scope** (shared with the team): |
| 54 | + |
| 55 | +``` |
| 56 | +title: "JWT refresh token rotation" |
| 57 | +type: decision |
| 58 | +scope: project |
| 59 | +content: **What**: Rotate refresh tokens on every use, invalidate the |
| 60 | +old one immediately. **Why**: prevents replay attacks if a token leaks |
| 61 | +in transit. **Where**: src/auth/refresh.ts. |
| 62 | +``` |
| 63 | + |
| 64 | +**Personal scope** (your own workspace): |
| 65 | + |
| 66 | +``` |
| 67 | +title: "Postgres EXPLAIN cheatsheet" |
| 68 | +type: learning |
| 69 | +scope: personal |
| 70 | +content: **What**: Quick reference for reading EXPLAIN output. |
| 71 | +**Learned**: Sequential scans on a 10k row table are usually fine; |
| 72 | +worry when you see them on tables with >100k rows. |
| 73 | +``` |
| 74 | + |
| 75 | +--- |
| 76 | + |
| 77 | +## Language strategy for shared memory |
| 78 | + |
| 79 | +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. |
| 80 | + |
| 81 | +### Convention |
| 82 | + |
| 83 | +- **`scope: project`** → save in the team's lingua franca. For most international teams this is English, matching code, commits, and PRs. |
| 84 | +- **`scope: personal`** → save in any language you prefer. Nobody else searches your personal scope, so language drift has no cost. |
| 85 | + |
| 86 | +### Why this matters |
| 87 | + |
| 88 | +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. |
| 89 | + |
| 90 | +Picking one language for shared memory keeps the search index coherent. Personal scope stays free for whatever language helps you think. |
| 91 | + |
| 92 | +--- |
| 93 | + |
| 94 | +## Adopting these conventions on a team |
| 95 | + |
| 96 | +The mechanics are already in place; what teams need is a written agreement. Three concrete steps: |
| 97 | + |
| 98 | +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. |
| 99 | +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. |
| 100 | +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. |
| 101 | + |
| 102 | +--- |
| 103 | + |
| 104 | +## Sync behavior today (read this if you collaborate) |
| 105 | + |
| 106 | +Two flows move observations off your machine: |
| 107 | + |
| 108 | +- **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. |
| 109 | +- **Local `engram sync`.** Exports project-scoped chunks to `.engram/` for sharing via git or any file-based transport. |
| 110 | + |
| 111 | +Both flows export observations of the target project regardless of their scope. `personal` does not stay local automatically. The recommended pattern today: |
| 112 | + |
| 113 | +- **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. |
| 114 | +- **Truly personal notes** → either (a) save them under a separate project name that you do not enroll, or (b) keep them off Engram entirely. |
| 115 | + |
| 116 | +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. |
| 117 | + |
| 118 | +--- |
| 119 | + |
| 120 | +## Related docs |
| 121 | + |
| 122 | +- [`docs/AGENT-SETUP.md`](AGENT-SETUP.md) — per-agent setup, Memory Protocol, autosync toggle. |
| 123 | +- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) — session lifecycle, topic keys, memory hygiene. |
| 124 | +- [`docs/engram-cloud/README.md`](engram-cloud/README.md) — Engram Cloud overview and enrollment. |
| 125 | +- [`DOCS.md`](../DOCS.md) — full reference for tools, endpoints, and storage. |
0 commit comments