Skip to content

[Sync] Clarify aindex sync semantics and skip non-git-managed project dirs #359

@zjarlin

Description

@zjarlin

Problem Summary

The current sync semantics are easy to misinterpret and can become dangerous when a user is using someone else's aindex.

In that case, memory-sync may force-sync the aindex project into <workspaceDir>, even when the real project path should not be materialized or managed there in the first place.

This creates ambiguity around what is considered the authoritative project location, and may lead to unintended writes or implicit project creation under <workspaceDir>.

Why This Is Problematic

1. Semantic ambiguity

The current behavior makes it unclear whether <workspaceDir> is:

  • merely a synchronization workspace, or
  • an authoritative project root that memory-sync is allowed to materialize and manage

When the input aindex originates from another person or another machine, forcing it into <workspaceDir> can violate user expectations.

2. Unsafe sync behavior for non-git-managed directories

If a <project> directory under <workspaceDir> is not actually git-managed, syncing into it is risky:

  • the directory may be incomplete or accidental
  • it may not represent a real tracked project
  • it may have been created only as a side effect of prior sync behavior

From an agent-first perspective, this should be treated conservatively.

3. Hidden partial-sync behavior

Some aindex sections such as app, ext, arch, and softwares may already be skipped during sync, but the user is not clearly warned that these parts were ignored.

That makes the result look more complete than it actually is.

Suggested Design Direction

A. Diff the real <project> path under <workspaceDir> before syncing

Before synchronizing, memory-sync should first inspect or diff the real <project> path under <workspaceDir>.

If the target directory is not an actually git-managed directory, the tool should:

  • emit a warning
  • skip synchronization for that <project>
  • avoid creating or force-populating the directory

B. Stop supporting sync into non-git-managed <project> directories

A stronger policy option would be:

No longer support syncing <project> directories that are not git-managed.

This would align well with the agent-first principle:

  • prefer explicit, inspectable, versioned project state
  • avoid mutating ambiguous local directories
  • reduce accidental writes caused by misleading workspace semantics

C. Explicit warnings for skipped aindex sections

If parts of an aindex are intentionally skipped, the tool should clearly warn the user.

At minimum, the warning should mention that some sections were not synchronized, for example:

  • app
  • ext
  • arch
  • softwares

This should be visible in CLI output (and GUI if applicable), so users understand they received a partial sync result rather than a complete one.

Expected Behavior

  • memory-sync should not blindly materialize or sync someone else's aindex into <workspaceDir>.
  • Sync should proceed only when the target <project> directory is confirmed to be git-managed.
  • Otherwise, the tool should warn and skip.
  • Users should also be explicitly informed when parts of aindex were skipped and not synchronized.

Motivation

This would make sync behavior:

  • less ambiguous
  • safer
  • more aligned with repository-backed workflows
  • more honest about partial synchronization results

Possible UX Wording

For non-git-managed target directories:

Warning: target project directory under <workspaceDir> is not git-managed; synchronization has been skipped.

For skipped aindex sections:

Warning: some aindex sections were skipped and not synchronized (app, ext, arch, softwares).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestmediumMedium priorityrustRust SDK/CLI/MCP code

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions