From 0385721c9f1b89a9b16cf5091a6db8dbe1eed7af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20G=C3=B3mez=20Navarro?= Date: Tue, 14 Apr 2026 16:39:34 +0200 Subject: [PATCH 1/8] docs: add team usage guide for scope and language conventions Add comprehensive team usage documentation covering: - Scope mental model (project vs personal) - Language strategy for multilingual teams - What to save in each scope with examples - Git sync workflow for teams and personal use - FAQ addressing common questions Resolves #175 --- DOCS.md | 1 + README.md | 1 + docs/TEAM-USAGE.md | 392 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 394 insertions(+) create mode 100644 docs/TEAM-USAGE.md diff --git a/DOCS.md b/DOCS.md index 1ab0312c..f7efba45 100644 --- a/DOCS.md +++ b/DOCS.md @@ -28,6 +28,7 @@ For other docs: |-----|-------------| | [Installation](docs/INSTALLATION.md) | All install methods + platform support | | [Agent Setup](docs/AGENT-SETUP.md) | Per-agent configuration + compaction survival | +| [Team Usage](docs/TEAM-USAGE.md) | Scope conventions, language strategy, git sync for teams | | [Architecture](docs/ARCHITECTURE.md) | How it works, session lifecycle, CLI reference, project structure | | [Plugins](docs/PLUGINS.md) | OpenCode & Claude Code plugin details | | [Comparison](docs/COMPARISON.md) | Why Engram vs claude-mem | diff --git a/README.md b/README.md index 5e5c3730..0a1e5754 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@

Installation • Agent Setup • + Team Usage • Architecture • Plugins • Contributing • diff --git a/docs/TEAM-USAGE.md b/docs/TEAM-USAGE.md new file mode 100644 index 00000000..fc5c4060 --- /dev/null +++ b/docs/TEAM-USAGE.md @@ -0,0 +1,392 @@ +[← Back to README](../README.md) + +# Team Usage Guide + +**How to use Engram collaboratively with shared project memory** + +This guide covers scope conventions, language strategy, and git sync workflows for teams using Engram to share knowledge across developers and AI agents. + +--- + +## Table of Contents + +- [Scope Mental Model](#scope-mental-model) +- [Language Convention](#language-convention) +- [What to Save in Each Scope](#what-to-save-in-each-scope) +- [Git Sync for Teams](#git-sync-for-teams) +- [FAQ](#faq) + +--- + +## Scope Mental Model + +Every observation in Engram has a `scope` parameter with two possible values: + +### `scope: project` (default) + +**Shared team memory** — visible to all team members and their AI agents. + +- Syncs via git to the team's shared sync repository +- Accessible to everyone working on the project +- Searchable by all teammates and their agents +- Use for decisions, patterns, conventions, and discoveries that benefit the whole team + +### `scope: personal` + +**Your personal workspace** — visible only to you and your AI agents. + +- Syncs via git to your personal sync repository (separate from the team repo) +- Only accessible on your devices +- Not shared with teammates +- Use for your own learnings, preferences, notes, and explorations + +### Rule of Thumb + +Ask yourself: **"Should a teammate's AI agent find this?"** + +- **Yes** → `scope: project` +- **No** → `scope: personal` + +--- + +## Language Convention + +### The Problem + +When teams share project memory via `engram sync`, a language mismatch can fragment the knowledge base: + +- Developer A (Spanish speaker) saves an observation in Spanish: `"Implementamos autenticación JWT en auth.go"` +- Developer B (English speaker) searches: `"How does authentication work?"` +- **Result**: No match. The English query doesn't match Spanish content, even though both observations are about the same code. + +FTS5 (Engram's full-text search engine) is language-agnostic but **not multilingual** — it cannot match queries in one language against content in another. + +### The Solution + +**Establish a lingua franca for `scope: project` observations.** + +For most international teams, this is **English** — the same language used for: +- Code (variable names, function names, comments) +- Commit messages +- Pull request descriptions +- Documentation + +### Recommended Convention + +| Scope | Language | +|-------|----------| +| `scope: project` | Team's lingua franca (usually English) | +| `scope: personal` | Any language you prefer | + +**Why this works**: +- All teammates can search and find shared memories, regardless of their native language +- Personal notes remain flexible — use the language most comfortable for your own learning +- AI agents can discover cross-team knowledge without language barriers + +**Example for a Spanish-speaking team at a US company**: + +```bash +# Shared project memory — always English +engram mcp < +git commit -m "remove: sensitive observation #123" +git push +``` + +Then notify your team to pull and re-import. + +### Can I have different `scope` conventions per project? + +Yes. Each project has its own observations. You can configure scope/language conventions per-project if your team works on multiple projects with different norms. + +--- + +## Summary + +| Aspect | `scope: project` | `scope: personal` | +|--------|------------------|-------------------| +| **Visibility** | Shared with team | Only you | +| **Language** | Team lingua franca (usually English) | Any language | +| **Sync repo** | Team's shared git repo | Your personal git repo | +| **Use for** | Decisions, patterns, discoveries, team conventions | Personal learnings, preferences, experiments | + +**Golden rule**: If a teammate's AI agent should find it → `scope: project` in the team's lingua franca. Otherwise → `scope: personal` in any language. + +--- + +## Further Reading + +- [DOCS.md](../DOCS.md) — Full technical reference for Engram +- [Agent Setup](AGENT-SETUP.md) — Configure Engram for your AI agent +- [Architecture](ARCHITECTURE.md) — How Engram works under the hood From 2043dc3001a773d611801df25b09da05b58d3097 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20G=C3=B3mez=20Navarro?= Date: Tue, 14 Apr 2026 18:13:20 +0200 Subject: [PATCH 2/8] fix(docs): correct TEAM-USAGE.md based on actual sync implementation Address all 6 issues identified by Copilot review: 1. Clarify scope:personal behavior - sync exports ALL observations for a project regardless of scope. Updated to recommend separate projects for truly private notes. 2. Fix sync commands - replace fictional flags (--scope, --output, --input) with real CLI: --import, --project, --all 3. Document actual .engram/ structure - chunks/*.jsonl.gz + manifest.json, explain append-only chunk design 4. Remove broken MCP JSON examples - replace with conceptual examples showing how agents use mem_save, avoid manual JSON-RPC calls 5. Correct FAQ answers - scope:personal DOES sync with project, not separate repo. Add warnings about this behavior. 6. Fix sensitive data removal instructions - explain chunk-based storage makes single observation removal complex, recommend git filter-branch or credential rotation All documentation now matches internal/sync/sync.go implementation. --- docs/TEAM-USAGE.md | 272 ++++++++++++++++++++++++--------------------- 1 file changed, 144 insertions(+), 128 deletions(-) diff --git a/docs/TEAM-USAGE.md b/docs/TEAM-USAGE.md index fc5c4060..9b7bd6ee 100644 --- a/docs/TEAM-USAGE.md +++ b/docs/TEAM-USAGE.md @@ -35,11 +35,15 @@ Every observation in Engram has a `scope` parameter with two possible values: **Your personal workspace** — visible only to you and your AI agents. -- Syncs via git to your personal sync repository (separate from the team repo) -- Only accessible on your devices -- Not shared with teammates +- Only visible in local database queries filtered by `scope: personal` +- Not shared with teammates in normal workflows - Use for your own learnings, preferences, notes, and explorations +**Important**: `engram sync` exports **all observations for a project**, regardless of scope. If you sync a project containing `scope: personal` observations to a shared git repository, teammates will import them. To keep personal notes truly private: +- Use a different project name (e.g., `myproject-personal` vs `myproject`) +- Maintain a separate `.engram/` sync directory for personal projects +- Or simply avoid using `scope: personal` for sensitive information in shared projects + ### Rule of Thumb Ask yourself: **"Should a teammate's AI agent find this?"** @@ -85,37 +89,17 @@ For most international teams, this is **English** — the same language used for **Example for a Spanish-speaking team at a US company**: -```bash -# Shared project memory — always English -engram mcp < "Save this to project memory: Next.js middleware runs on edge runtime and cannot use Node.js fs module. I discovered this while trying to read config files in middleware. Use environment variables or edge-compatible APIs instead." + +The agent will create an observation with: +- Title: "Next.js middleware edge runtime limitation" +- Type: `discovery` +- Scope: `project` +- Content formatted with What/Why/Where/Learned structure --- @@ -198,22 +175,11 @@ Use for your own notes, experiments, and preferences: **Example**: -```bash -engram mcp < "Save to my personal notes: I prefer Zustand over Redux for small projects because it has less boilerplate and a simpler API. Redux is still better for large apps with complex state." + +The agent will create an observation with scope `personal` — visible only in your local database. --- @@ -221,10 +187,26 @@ EOF Engram uses git to sync observations across devices and teammates. -### Setup Overview +### How Sync Works -1. **Team sync repository** — shared repo for `scope: project` observations -2. **Personal sync repository** — your own repo for `scope: personal` observations +`engram sync` exports observations to a `.engram/` directory structure: + +``` +.engram/ +├── manifest.json ← Index of all chunks (small, mergeable) +├── chunks/ +│ ├── a3f8c1d2.jsonl.gz ← Chunk 1 (gzipped JSONL) +│ ├── b7d2e4f1.jsonl.gz ← Chunk 2 +│ └── ... +└── sync_chunks ← Tracks imported chunks (prevents duplicates) +``` + +**Key points**: +- Each `engram sync` creates a **new chunk** (never modifies old ones → no git conflicts) +- Sync is **project-based**, not scope-based +- By default, syncs observations for the current project (detected from git repo) +- Use `--all` to export ALL projects +- Use `--project ` to specify a different project ### Team Sync Workflow @@ -238,65 +220,70 @@ One team member creates a git repo for shared project memory: # Make it private if your project is proprietary ``` -#### Step 2: Each Developer Configures the Team Sync Repo +#### Step 2: Clone and Initialize + +Each team member clones the sync repo: ```bash -# Clone the team sync repo +# Clone the team sync repo to your local machine git clone git@github.com:your-org/your-project-engram-sync.git ~/team-engram-sync +cd ~/team-engram-sync -# Configure engram to use it for project-scoped observations -# (This would be done via engram CLI — consult `engram sync --help` for exact commands) +# Initial sync structure will be created automatically on first export ``` -#### Step 3: Regular Sync +#### Step 3: Regular Sync Workflow ```bash -# Export project-scoped observations to git -engram sync export --scope project --output ~/team-engram-sync - -# Commit and push +# Navigate to the sync repository cd ~/team-engram-sync -git add . -git commit -m "sync: update project memory" -git push -# Pull teammates' updates +# Pull latest changes from teammates git pull -# Import into your local engram database -engram sync import --scope project --input ~/team-engram-sync +# Import new chunks into your local database +engram sync --import + +# Work on the project, create observations with your AI agent +# ... + +# Export new observations to the sync repo +# (Run this from the sync repo directory) +engram sync --project myproject + +# Or export ALL projects: +# engram sync --all + +# Commit and push the new chunk +git add .engram/ +git commit -m "sync: add new observations" +git push ``` -**Tip**: Automate this with a git hook or cron job. +**Tip**: The sync repo should contain ONLY the `.engram/` directory. Run `engram sync` from inside the sync repo, or automate with a git hook. --- -### Personal Sync Workflow +### Syncing Personal Notes Separately -For syncing your personal observations across your own devices: +If you want to keep personal notes on multiple devices **without sharing them with the team**, use a separate project name: ```bash -# Create your personal sync repo (private) -# Example: your-username/engram-personal-sync - -# Clone it -git clone git@github.com:your-username/engram-personal-sync.git ~/personal-engram-sync +# Use a different project name for personal work +# Example: when saving personal observations, use project "myname-notes" -# Export personal observations -engram sync export --scope personal --output ~/personal-engram-sync +# Create a separate sync repo (private) +git clone git@github.com:your-username/engram-personal.git ~/engram-personal +cd ~/engram-personal -# Commit and push -cd ~/personal-engram-sync -git add . -git commit -m "sync: laptop to desktop" -git push +# Sync only your personal project +engram sync --project myname-notes -# On another device: pull and import -cd ~/personal-engram-sync -git pull -engram sync import --scope personal --input ~/personal-engram-sync +# This keeps your personal notes separate from the team's shared project ``` +**Important**: `engram sync` exports ALL observations for a project, including both `scope: project` and `scope: personal`. The `scope` field is a logical filter for queries, not an access control mechanism. If you mix personal and team observations in the same project and sync it, teammates will import everything. + --- ## FAQ @@ -315,31 +302,40 @@ Example: A team in Spain where everyone speaks Spanish can use Spanish for share ### Do personal observations sync to the team repo? -**No**. `scope: personal` observations only sync to your **personal sync repository**, not the team's shared repo. +**It depends**. `engram sync` exports ALL observations for a project, regardless of scope. If you have both `scope: personal` and `scope: project` observations in the same project and run `engram sync`, both will be exported to the sync repo. + +To keep personal notes separate: +- Use a different project name for personal work (e.g., `myname-notes`) +- Sync that project to a separate, private git repository +- Never sync personal projects to the team's shared repo + +The `scope` field is a logical filter for queries (e.g., `mem_search --scope personal`), not an access control mechanism for git sync. ### Can I change an observation's scope after saving it? -Yes. Use `mem_update` to change the `scope` field: +Yes. Ask your AI agent to update the observation's scope: + +> "Update observation #123 to scope: project" + +Or use the HTTP API directly: ```bash -engram mcp < -git commit -m "remove: sensitive observation #123" -git push +# Identify which chunk contains the observation (check manifest.json timestamps) +# Remove the chunk file and update manifest.json +git filter-branch --force --index-filter \ + "git rm --cached --ignore-unmatch .engram/chunks/.jsonl.gz" HEAD +git push --force ``` -Then notify your team to pull and re-import. +**Option B: Accept the exposure** and rotate credentials: +- The chunk is already distributed to teammates who ran `git pull` +- Assume the secret is compromised +- Rotate the leaked credential/token immediately +- Delete the observation locally to prevent future exports + +3. **Notify teammates** to: + - Pull the updated repo (if you rewrote history) + - Delete the observation from their local databases + - Update any affected credentials + +**Prevention**: Avoid saving API keys, tokens, or passwords in observations. Use environment variables or secret management tools instead. ### Can I have different `scope` conventions per project? @@ -376,12 +391,13 @@ Yes. Each project has its own observations. You can configure scope/language con | Aspect | `scope: project` | `scope: personal` | |--------|------------------|-------------------| -| **Visibility** | Shared with team | Only you | +| **Visibility** | Shared with team via queries | Only visible in filtered queries | | **Language** | Team lingua franca (usually English) | Any language | -| **Sync repo** | Team's shared git repo | Your personal git repo | +| **Sync behavior** | Exported with project to git | Exported with project to git (same as project scope) | +| **Best practice** | Use for team knowledge | Use in separate project, sync to private repo | | **Use for** | Decisions, patterns, discoveries, team conventions | Personal learnings, preferences, experiments | -**Golden rule**: If a teammate's AI agent should find it → `scope: project` in the team's lingua franca. Otherwise → `scope: personal` in any language. +**Golden rule**: If a teammate's AI agent should find it → `scope: project` in the team's lingua franca. For truly private notes → use a separate project name and sync to a private repo. --- From a013a719c3207028efba883e010a0eaaeed5a379 Mon Sep 17 00:00:00 2001 From: Enrique Gomez Date: Tue, 14 Apr 2026 18:23:28 +0200 Subject: [PATCH 3/8] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/TEAM-USAGE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/TEAM-USAGE.md b/docs/TEAM-USAGE.md index 9b7bd6ee..9fd0666a 100644 --- a/docs/TEAM-USAGE.md +++ b/docs/TEAM-USAGE.md @@ -33,10 +33,11 @@ Every observation in Engram has a `scope` parameter with two possible values: ### `scope: personal` -**Your personal workspace** — visible only to you and your AI agents. +**Your personal workspace** — intended for observations that are local to you and your AI agents. -- Only visible in local database queries filtered by `scope: personal` -- Not shared with teammates in normal workflows +- `scope` is a logical tag/filter, not a hidden/private storage mode +- Search tools may include both `project` and `personal` observations by default unless you apply a `scope` filter +- Not shared with teammates in normal workflows unless you export or sync them - Use for your own learnings, preferences, notes, and explorations **Important**: `engram sync` exports **all observations for a project**, regardless of scope. If you sync a project containing `scope: personal` observations to a shared git repository, teammates will import them. To keep personal notes truly private: From aeb5bd5b5ad6e01966074bd434bebc90c3245259 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20G=C3=B3mez=20Navarro?= Date: Tue, 14 Apr 2026 18:34:28 +0200 Subject: [PATCH 4/8] fix(docs): address 10 additional Copilot review findings in TEAM-USAGE.md - Clarify scope is a filter/tag, not access control (visibility section) - Fix mem_search example (scope is JSON param, not CLI flag) - Remove duplicate 'Example:' labels in workflows - Update summary table (scope as filter vs access control) - Correct .engram/ structure diagram (chunks are gzipped JSON, not JSONL) - Document sync_chunks as SQLite table, not directory file - Replace deprecated git filter-branch with git-filter-repo - Add collaborator impact warning for history rewrites - Fix scope filtering description in summary table --- docs/TEAM-USAGE.md | 44 +++++++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/docs/TEAM-USAGE.md b/docs/TEAM-USAGE.md index 9b7bd6ee..ebc2541f 100644 --- a/docs/TEAM-USAGE.md +++ b/docs/TEAM-USAGE.md @@ -33,10 +33,11 @@ Every observation in Engram has a `scope` parameter with two possible values: ### `scope: personal` -**Your personal workspace** — visible only to you and your AI agents. +**Your personal workspace** — a logical tag for organizing observations. -- Only visible in local database queries filtered by `scope: personal` -- Not shared with teammates in normal workflows +- `scope` is a filter/tag, not an access control mechanism +- Searches without a scope filter return BOTH `project` and `personal` observations +- The `scope` field appears in results so you can distinguish them - Use for your own learnings, preferences, notes, and explorations **Important**: `engram sync` exports **all observations for a project**, regardless of scope. If you sync a project containing `scope: personal` observations to a shared git repository, teammates will import them. To keep personal notes truly private: @@ -136,8 +137,6 @@ Use for knowledge that helps the whole team: - Local development setup steps - CI/CD pipeline quirks -**Example**: - **Example**: Ask your AI agent to save a discovery about Next.js middleware: > "Save this to project memory: Next.js middleware runs on edge runtime and cannot use Node.js fs module. I discovered this while trying to read config files in middleware. Use environment variables or edge-compatible APIs instead." @@ -173,8 +172,6 @@ Use for your own notes, experiments, and preferences: - Ideas to explore later - Personal TODO items -**Example**: - **Example**: Ask your AI agent to save a personal preference: > "Save to my personal notes: I prefer Zustand over Redux for small projects because it has less boilerplate and a simpler API. Redux is still better for large apps with complex state." @@ -194,15 +191,16 @@ Engram uses git to sync observations across devices and teammates. ``` .engram/ ├── manifest.json ← Index of all chunks (small, mergeable) -├── chunks/ -│ ├── a3f8c1d2.jsonl.gz ← Chunk 1 (gzipped JSONL) -│ ├── b7d2e4f1.jsonl.gz ← Chunk 2 -│ └── ... -└── sync_chunks ← Tracks imported chunks (prevents duplicates) +└── chunks/ + ├── a3f8c1d2.jsonl.gz ← Chunk 1 (gzipped JSON) + ├── b7d2e4f1.jsonl.gz ← Chunk 2 + └── ... ``` **Key points**: - Each `engram sync` creates a **new chunk** (never modifies old ones → no git conflicts) +- Chunk files have `.jsonl.gz` extension but contain **gzipped JSON** (single object per chunk), not JSONL +- Imported chunk IDs are tracked in the **local SQLite database** (table `sync_chunks`), not in the `.engram/` directory - Sync is **project-based**, not scope-based - By default, syncs observations for the current project (detected from git repo) - Use `--all` to export ALL projects @@ -309,7 +307,7 @@ To keep personal notes separate: - Sync that project to a separate, private git repository - Never sync personal projects to the team's shared repo -The `scope` field is a logical filter for queries (e.g., `mem_search --scope personal`), not an access control mechanism for git sync. +The `scope` field is a logical filter for queries (e.g., your AI agent can filter searches by passing `scope: "personal"` as a parameter), not an access control mechanism for git sync. ### Can I change an observation's scope after saving it? @@ -362,12 +360,23 @@ The observation is embedded in a compressed chunk file (`.engram/chunks/*.jsonl. ```bash cd ~/team-engram-sync # Identify which chunk contains the observation (check manifest.json timestamps) -# Remove the chunk file and update manifest.json -git filter-branch --force --index-filter \ - "git rm --cached --ignore-unmatch .engram/chunks/.jsonl.gz" HEAD +# Remove the chunk file using git-filter-repo (recommended) or BFG Repo-Cleaner + +# Using git-filter-repo: +git filter-repo --path .engram/chunks/.jsonl.gz --invert-paths + +# Or using BFG: +# bfg --delete-files .jsonl.gz + git push --force ``` +**Important**: After rewriting history, all collaborators must either: +- Re-clone the repository, OR +- Run `git fetch --all && git reset --hard origin/main` (loses local changes) + +History rewriting is disruptive for teams. Use Option B if multiple people have already pulled the leaked chunk. + **Option B: Accept the exposure** and rotate credentials: - The chunk is already distributed to teammates who ran `git pull` - Assume the secret is compromised @@ -391,7 +400,8 @@ Yes. Each project has its own observations. You can configure scope/language con | Aspect | `scope: project` | `scope: personal` | |--------|------------------|-------------------| -| **Visibility** | Shared with team via queries | Only visible in filtered queries | +| **Visibility** | Included in all queries (default) | Included in all queries (default) | +| **Filtering** | Queries can filter to project-only | Queries can filter to personal-only | | **Language** | Team lingua franca (usually English) | Any language | | **Sync behavior** | Exported with project to git | Exported with project to git (same as project scope) | | **Best practice** | Use for team knowledge | Use in separate project, sync to private repo | From 3c7ebaa3572b718f3b26bb950a966dfa6c7cea88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20G=C3=B3mez=20Navarro?= Date: Tue, 14 Apr 2026 18:46:22 +0200 Subject: [PATCH 5/8] fix(docs): address Copilot review round 3 findings - Clarify scope: project sharing requires explicit export/sync/import steps - Fix sync behavior description: exports incrementally (new chunks), not all-at-once - Qualify personal scope visibility: local unless synced to shared repo - Correct git conflicts claim: manifest.json can still conflict during concurrent edits - Add Team Usage to README Documentation table for consistent discoverability --- README.md | 1 + docs/TEAM-USAGE.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 0a1e5754..994b26f6 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,7 @@ Full CLI with all flags → [docs/ARCHITECTURE.md#cli-reference](docs/ARCHITECTU |-----|-------------| | [Installation](docs/INSTALLATION.md) | All install methods + platform support | | [Agent Setup](docs/AGENT-SETUP.md) | Per-agent configuration + Memory Protocol | +| [Team Usage](docs/TEAM-USAGE.md) | Scope conventions, language strategy, git sync for teams | | [Architecture](docs/ARCHITECTURE.md) | How it works + MCP tools + project structure | | [Plugins](docs/PLUGINS.md) | OpenCode & Claude Code plugin details | | [Comparison](docs/COMPARISON.md) | Why Engram vs claude-mem | diff --git a/docs/TEAM-USAGE.md b/docs/TEAM-USAGE.md index ebc2541f..4e81fa98 100644 --- a/docs/TEAM-USAGE.md +++ b/docs/TEAM-USAGE.md @@ -24,12 +24,11 @@ Every observation in Engram has a `scope` parameter with two possible values: ### `scope: project` (default) -**Shared team memory** — visible to all team members and their AI agents. +**Shared team memory** — intended for knowledge that benefits the whole team. -- Syncs via git to the team's shared sync repository -- Accessible to everyone working on the project -- Searchable by all teammates and their agents -- Use for decisions, patterns, conventions, and discoveries that benefit the whole team +- Included in all queries by default (visible to all agents) +- When you export/sync to a shared git repo and teammates import, they receive these observations +- Use for decisions, patterns, conventions, and discoveries the team should know about ### `scope: personal` @@ -40,7 +39,7 @@ Every observation in Engram has a `scope` parameter with two possible values: - The `scope` field appears in results so you can distinguish them - Use for your own learnings, preferences, notes, and explorations -**Important**: `engram sync` exports **all observations for a project**, regardless of scope. If you sync a project containing `scope: personal` observations to a shared git repository, teammates will import them. To keep personal notes truly private: +**Important**: When you run `engram sync`, it exports observations for the specified project (including both `scope: project` and `scope: personal`) into a new chunk. Over time, these chunks collectively contain all observations you've exported for that project. If you sync to a shared git repository and teammates import, they receive everything — regardless of scope. To keep personal notes truly private: - Use a different project name (e.g., `myproject-personal` vs `myproject`) - Maintain a separate `.engram/` sync directory for personal projects - Or simply avoid using `scope: personal` for sensitive information in shared projects @@ -176,7 +175,7 @@ Use for your own notes, experiments, and preferences: > "Save to my personal notes: I prefer Zustand over Redux for small projects because it has less boilerplate and a simpler API. Redux is still better for large apps with complex state." -The agent will create an observation with scope `personal` — visible only in your local database. +The agent will create an observation with scope `personal` — visible in your local database (and included if you later sync/export this project to a shared repo). --- @@ -198,7 +197,8 @@ Engram uses git to sync observations across devices and teammates. ``` **Key points**: -- Each `engram sync` creates a **new chunk** (never modifies old ones → no git conflicts) +- Each `engram sync` creates a **new chunk** (never modifies old ones), minimizing conflicts +- `manifest.json` is updated on each export and can still conflict during concurrent edits; pulling before exporting reduces manifest merge conflicts - Chunk files have `.jsonl.gz` extension but contain **gzipped JSON** (single object per chunk), not JSONL - Imported chunk IDs are tracked in the **local SQLite database** (table `sync_chunks`), not in the `.engram/` directory - Sync is **project-based**, not scope-based From 57dc48d66b5ed883164899b1e504f8d30cd9e8d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20G=C3=B3mez=20Navarro?= Date: Tue, 14 Apr 2026 19:00:04 +0200 Subject: [PATCH 6/8] fix(docs): clarify scope behavior and terminology per Copilot review - scope: project is default when saving (queries include both unless filtered) - Rule of Thumb: add caveat that personal scope syncs with project to shared repos - JSONL terminology: clarify chunks are 'single JSON object' despite .jsonl.gz extension Note: Table syntax findings (lines 81, 408) are false positives - tables use correct standard Markdown (single | per row, verified with byte inspection) --- docs/TEAM-USAGE.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/TEAM-USAGE.md b/docs/TEAM-USAGE.md index 4e81fa98..bb87c8a7 100644 --- a/docs/TEAM-USAGE.md +++ b/docs/TEAM-USAGE.md @@ -26,7 +26,8 @@ Every observation in Engram has a `scope` parameter with two possible values: **Shared team memory** — intended for knowledge that benefits the whole team. -- Included in all queries by default (visible to all agents) +- Default scope when saving observations (if not explicitly set to `personal`) +- Included in queries unless caller filters to `scope: personal` only - When you export/sync to a shared git repo and teammates import, they receive these observations - Use for decisions, patterns, conventions, and discoveries the team should know about @@ -49,7 +50,9 @@ Every observation in Engram has a `scope` parameter with two possible values: Ask yourself: **"Should a teammate's AI agent find this?"** - **Yes** → `scope: project` -- **No** → `scope: personal` +- **No** → `scope: personal` (but remember: if you sync this project to a shared repo, teammates will still import personal-scope observations) + +For truly private notes, use a separate project name (e.g., `myproject-personal`) and sync to a private git repo. --- @@ -199,7 +202,7 @@ Engram uses git to sync observations across devices and teammates. **Key points**: - Each `engram sync` creates a **new chunk** (never modifies old ones), minimizing conflicts - `manifest.json` is updated on each export and can still conflict during concurrent edits; pulling before exporting reduces manifest merge conflicts -- Chunk files have `.jsonl.gz` extension but contain **gzipped JSON** (single object per chunk), not JSONL +- Chunk files have `.jsonl.gz` extension but currently contain **a single gzipped JSON object** (despite the `.jsonl.gz` naming) - Imported chunk IDs are tracked in the **local SQLite database** (table `sync_chunks`), not in the `.engram/` directory - Sync is **project-based**, not scope-based - By default, syncs observations for the current project (detected from git repo) From 91991786e64bbbb60242f5e5e03fdb02ecc64ed1 Mon Sep 17 00:00:00 2001 From: Enrique Gomez Date: Tue, 14 Apr 2026 19:09:58 +0200 Subject: [PATCH 7/8] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- 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 bb87c8a7..ac1b5639 100644 --- a/docs/TEAM-USAGE.md +++ b/docs/TEAM-USAGE.md @@ -261,7 +261,7 @@ git commit -m "sync: add new observations" git push ``` -**Tip**: The sync repo should contain ONLY the `.engram/` directory. Run `engram sync` from inside the sync repo, or automate with a git hook. +**Tip**: The sync repo should contain ONLY the `.engram/` directory. When running `engram sync` from inside a dedicated sync repo, always pass `--project ` (or use `--all`, or set `ENGRAM_PROJECT`) so Engram does not auto-detect the sync repo name as the project. You can also automate this with a git hook. --- From a08c566147550194c79ff9eeb2e38aff0616ee04 Mon Sep 17 00:00:00 2001 From: Enrique Gomez Date: Tue, 14 Apr 2026 19:16:37 +0200 Subject: [PATCH 8/8] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- 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 ac1b5639..0197f49d 100644 --- a/docs/TEAM-USAGE.md +++ b/docs/TEAM-USAGE.md @@ -261,7 +261,7 @@ git commit -m "sync: add new observations" git push ``` -**Tip**: The sync repo should contain ONLY the `.engram/` directory. When running `engram sync` from inside a dedicated sync repo, always pass `--project ` (or use `--all`, or set `ENGRAM_PROJECT`) so Engram does not auto-detect the sync repo name as the project. You can also automate this with a git hook. +**Tip**: The sync repo should contain ONLY the `.engram/` directory. When running `engram sync` from inside a dedicated sync repo, always pass `--project ` (or use `--all`) so Engram does not auto-detect the sync repo name as the project. If you want to automate this, use a shell alias or wrapper script that always runs `engram sync --project `. You can also automate this with a git hook. ---