Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

feat(sync): opt-in personal-scope export for `engram sync --project`

Open
  • Is something wrong?
#1,407 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
72/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
backend, cli

Research direction

Start at the scope filter in internal/sync/sync.go around lines 2079-2091 (the v2.2.0 link in the issue) to see where personal-scope observations and relations with a personal endpoint are skipped, then find where engram sync --project parses its flags to plumb an opt-in like --include-personal. Keep the default path untouched and verify the #701 guarantee that a relation ships only when both endpoints reach the receiver. Done means the flag exports the project's personal-scope rows and their in-project relations, the v2.x default is unchanged, and docs/TEAM-USAGE.md lines 104-116 describe the new behavior.

Written by the indexing model from the issue text.

Description

priority:medium status:needs-review type:feature
🔍 Problem Description

I use Engram on my own, on Linux and Windows with a separate store on each, and move memory between them through a private Git repository with local engram sync --project NAME, one reviewed project at a time. I keep cross-project preferences and decisions in scope: personal so they show up in personal context from any project (#425).

On v1.20.0, engram sync --project NAME exports the project's personal-scope observations with the rest, and my repository has v1.20.0 chunks that carry them. Since #784 (the fix for #701), v2.x exports only scope: project observations for a named project and skips relations with a personal endpoint (filter in v2.2.0). The run succeeds and nothing reports the skipped observations. I reproduced this on v2.1.0 with a copy of my store: the chunk left out the project's personal-scope observation and its three relations, and only engram sync --all exported them. The same code is in v2.2.0.

The docs still describe the v1.20.0 behavior. docs/TEAM-USAGE.md in v2.2.0 says local engram sync exports "observations of the target project regardless of their scope" and that changing this "needs a deliberate design decision" (L104-L116). #784 marked docs as not required and no release note mentions the change, so anyone syncing per project who upgrades from v1.20.0 stops syncing new and edited personal memories without being told. It's the reason I'm still on v1.20.0.

💡 Proposed Solution

Keep the 2.x default and add an explicit opt-in that lets a local per-project sync include that project's personal-scope observations and the relations that link them within the project. A flag such as engram sync --project NAME --include-personal or a per-project setting would both work for me.

The maintainer asked three contract questions in #474, which requested the opposite (keeping personal observations local for teams). My answers for this case:

  • Local or Cloud: local engram sync only. Cloud keeps its current behavior.
  • Default or opt-in: opt-in and off by default, so nothing changes for anyone who doesn't enable it.
  • Existing rows: untouched unless the opt-in is used. When it is, the project's personal-scope observations that earlier 2.x runs skipped should be exported too.

Relations should keep the #701 guarantee: a relation travels only when both of its endpoints reach the receiver as well. Since #1374 (v2.2.0), import already applies same-project relations regardless of endpoint scope, so receivers should need no change.

Whatever you decide, the docs and the code should agree on what local sync does with personal scope.

📦 Affected Area

Sync (multi-instance)

🔄 Alternatives Considered
  • engram sync --all includes personal scope, but it exports every project in one run. I publish one reviewed project at a time and keep some records out of Git on purpose.
  • Cloud sync needs an Engram Cloud server, and my memory only moves through a private Git repository.
  • Re-scoping these memories to project would remove them from cross-project personal search and context (#425).
📎 Additional Context

No response

Dominant language
Go
Stars
7.1k
Forks
729
Avg merge
11h 17m
Merged PRs (30d)
334

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Gentleman-Programming/engram

All issues in Gentleman-Programming/engram

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.