docs: add team usage guide — scope conventions and language strategy for shared memory

[carlosmoradev]

📋 Pre-flight Checks

• I searched existing issues and this is not a duplicate
• I have a link to the specific doc page or section that needs improvement → DOCS.md

---

📄 Which Document?

DOCS.md — missing team usage section.

---

🔍 What's Wrong or Missing?

DOCS.md documents Engram's mechanics well, but there is no guidance for teams adopting it collaboratively. Three specific gaps:

1. No mental model for scope: project vs scope: personal

The mem_save tool description only says:

"Scope for this observation: project (default) or personal"

There is no explanation of what this distinction means. A developer reading the docs cannot answer:

• Who can see each scope?
• Does git sync include personal observations?
• When should I use one vs the other?

2. No language convention for shared memory

When a team uses engram sync to share project memory, there is no guidance on what language to use for scope: project observations.

Real scenario: a Spanish-speaking team works for a US English company. Code, commits, and PRs are in English. Personal notes (outside Engram) are in Spanish. But for scope: project Engram observations — no convention exists.

For globally distributed teams (e.g. Russian, French, Japanese, and English speakers on the same project), the consequences are concrete: if each developer saves project-scope memories in their native language, the shared knowledge base fragments. FTS5 cannot match a query in English against an observation saved in Spanish, so team members effectively can't find each other's shared knowledge.

3. No guidance on what belongs in each scope

Without a clear mental model, developers default to saving everything as scope: project (the default), polluting shared memory with personal notes — or avoid scope: personal entirely, missing the value of having a personal workspace within the same tool.

---

💡 Suggested Improvement

A new docs/TEAM-USAGE.md (or a section added to DOCS.md) covering:

Scope mental model

• scope: project = shared via git sync, accessible to all team members and their agents
• scope: personal = your own workspace; syncs to your other devices via your personal sync repo, but not shared with teammates
• Rule of thumb: if a teammate's AI agent should find this → project; if it's your personal learning or preference → personal

Language convention

• scope: project → lingua franca of the team (English for most international teams)
• scope: personal → any language you prefer
• Why it matters: the lingua franca ensures all teammates can search and find shared memories regardless of native language. FTS5 is language-agnostic but not multilingual — a search in one language won't match content in another.

What to save in each scope (with examples)

Git sync workflow for teams

• How scope interacts with sync
• Personal sync repo (your devices) vs team sync repo (shared project)

I'm happy to write this documentation as a PR once approved.

---

📎 Additional Context

The scope parameter already supports this pattern by design — it just isn't explained. This is a documentation-only contribution with no code changes required.

The insight came from reasoning through a real cross-device + team-sharing use case: personal notes in any language syncing across my own devices, while shared team memory stays in the lingua franca. The system already handles this correctly — it just needs to be documented so other developers don't have to reason through it from scratch.

Originally reported in #175 (opened from wrong GitHub account).

[Alan-TheGentleman]

This is clear enough and in scope, so I am adding status:approved. A focused PR linking this issue is welcome. Keep the implementation tight and include regression coverage where behavior changes.

[carlosmoradev]

Quick heads up while opening the PR (#409): I checked the sync code path and the issue's framing that scope: personal does not get shared with teammates is not enforced today. internal/sync/sync.go exports every observation of an enrolled project regardless of scope.

The PR documents the current behavior accurately: scope is a search and filter signal, not a transport-level boundary. Two workarounds that work today are listed in the guide (separate project name, or do not enroll the shared project for cloud sync).

If you want scope-aware sync (personal stays on the machine, project syncs to the team), that is a separate code change worth its own issue. Happy to open one if you want to track it.