Resolve project identity from canonical repo URL, not directory basename

[thekoma]

Problem

After #687 made basename(git rev-parse --show-toplevel) the default project key, two failure modes remain:

1. Basename collisions — ~/work/utils (github.com/acme/utils) and ~/clients/foo/utils (github.com/foo/utils) both resolve to utils and silently share memory.
2. Cross-machine fragmentation — a single agentmemory pod serving multiple MCP clients sees the same repo as different projects when contributor checkouts differ in basename. Concrete shape: central pod at /srv/projects/foo, dev box at /home/<user>/src/foo, or simply foo-prod vs foo on a fork. AGENTMEMORY_PROJECT_NAME works around this but requires per-machine config for what is intrinsic to the repo.

Both fall away once the resolver consults remote.origin.url — the same identity src/hooks/post-commit.ts:65 already uses for commit attribution.

Proposal

Insert one step between the env override and the toplevel-basename fallback:

AGENTMEMORY_PROJECT_NAME
→ canonical(git config --get remote.origin.url)
→ basename(git rev-parse --show-toplevel)   ← #687, unchanged
→ basename(cwd)                              ← unchanged

canonical produces host/owner/repo:

Input	Output
https://github.com/acme/widgets.git	github.com/acme/widgets
git@github.com:Acme/Widgets.git	github.com/acme/widgets
ssh://git@host.example:2222/acme/widgets.git	host.example/acme/widgets
https://user:token@github.com/acme/widgets	github.com/acme/widgets

Lowercased end-to-end (host providers treat owner/repo case-insensitively; preserving path case would re-fragment same-repo clones). Trailing .git stripped, credentials stripped. Unparseable remotes fall through to basename.

Why this and not #530

#530 proposed canonicalization plus multi-key matching across canonical/cwd/worktree-top/main-root/aliases. This issue keeps the single-key partitioning #687 just shipped — the change is where the key comes from, not how it's matched. No migration of existing data; deployments that already set AGENTMEMORY_PROJECT_NAME see no behavior change.

Non-goals

• Monorepo sub-package partitioning. Every package under github.com/acme/monorepo resolves to the same key by design — partitioning within a monorepo is an orthogonal concern (the project axis isn't the right one for it). Operators who need per-package memory continue to set AGENTMEMORY_PROJECT_NAME per-package.
• Multi-remote awareness (forks). origin is sufficient for the two failure modes above. AGENTMEMORY_PROJECT_NAME remains the override for fork workflows that need to point at upstream.
• SSH config aliases, insteadOf rewrites. Resolver consumes the raw URL git emits; if a contributor configures an alias differently across machines, that's the same class of problem as setting different env vars and is solved by the same escape hatch.

Performance

One git config --get remote.origin.url invocation, capped at 500ms (same budget the rest of _project.ts already uses). Same shape as #530's tightened lookup discussed by @rockarxiv on that PR.

Patch shape

~60 LOC in src/hooks/_project.ts, 12 new unit tests, full suite (1303 tests) green. Happy to discuss the approach before opening the PR if there's a different shape you'd prefer; otherwise the PR will follow.

[garyelephant]

This is very useful for me to use agentmemory across multi agent, claude, codex, opencode to keep consistent project name, I think your proposal should be a standard for project name.

[garyelephant]

Hi @rohitg00 , what do you think about this, can this proposal and impl be accepted ?

[thekoma]

Consolidating the project-identity work. Several open PRs now propose the same fix. Let's give @rohitg00 one direction instead of three competing diffs.

The cluster:

• Resolve project identity from canonical repo URL, not directory basename #716 / _project.ts: resolve project from canonical remote.origin.url #717 (this): canonical remote.origin.url → host/owner/repo, single-key, always-on, ~60 LOC in _project.ts.
• Project identity uses git-toplevel basename — collides across same-named repos, no remote-based identity #733 / Stable project identity from git remote + default remember to project scope #738 (@devon3000): same diagnosis, same seam, behind an opt-in AGENTMEMORY_PROJECT_FROM_REMOTE flag, plus a backfill-project-identity.mjs migration and MCP wiring.
• Add project isolation for agentmemory #829 (@Durocks): broader project isolation, scope threaded through every memory function and MCP boundary. It consumes the identity resolver rather than replacing it.
• fix(codex): canonicalize project identity for git worktrees #530 (closed): the multi-key worktree-alias route. We all picked single-key, which matches fix(hooks): send repo basename as project, not full path (#474) #687.

We agree on three things already: keep #687's single-key partitioning, source the key from the canonical remote (host/owner/repo, lowercased, credentials and .git stripped), and fall through to toplevel-basename then cwd when no remote parses.

One decision stays open: migration. Switching the key from agentmemory to github.com/rohitg00/agentmemory orphans every existing basename-keyed row, which breaks auto-context and the rolling project profile (see the analysis in #733). #717 ships always-on with no migration. #738 already covers this with the flag and the backfill. That gap shouldn't fork the work.

Proposed synthesis:

1. Take _project.ts: resolve project from canonical remote.origin.url #717's resolver, its URL-format table, and its tests.
2. Ship Stable project identity from git remote + default remember to project scope #738's backfill in the same change. The key changes for existing users, so migration is mandatory.
3. Pick a rollout: opt-in flag first, then flip the default once backfill bakes; or always-on plus backfill in one release. Both stay safe with the script in place.

@devon3000 I'll fold #717 into this and co-own whatever shape wins. @rohitg00 does single-key + canonical-remote + backfill match your plan, and do you want a flag or a clean default flip?

[rohitg00]

Bug is real and worth fixing. The part that needs more care is default-on without migration. Anyone on v0.9.x has memory keyed by basename, and orphaning that data on upgrade is something I want to avoid even when the new key is more correct.

Preferred direction:

1. Opt-in flag first (AGENTMEMORY_PROJECT_FROM_REMOTE=1) for a release or two so users can migrate on their own schedule.
2. Mandatory backfill script before flipping the default.
3. Identity resolution split from memory_save scope-defaulting. Separate seams, separate PRs.

#738 has roughly that shape (flag + backfill) but bundles the scope-default change. #717 has the cleaner identity-resolver code but ships without migration. #829 is project isolation enforcement and stays on its own track.

Could the two of you regroup on a single PR that takes #717's resolver + tests, gates it behind the opt-in flag, and ships #738's backfill alongside? The memory_save change can land separately. I'll review once it's in that shape.

[Durocks]

Let me add a little more context of what I think is the right direction. I'm using this logic in my branch and honestly it's saving me a lot of headaches trying to set the right variables in the MCP settings and plugins.

The way it works is simple. The AGENTMEMORY_PROJECT_ISOLATION variable is set to true by default. When set to true, the project variable becomes mandatory and the MCP instructs the AI to include the variable, failing with a 400 error if not provided. And if AGENTMEMORY_PROJECT_NAME is not passed (Even better if it's not passed, as it's less effort from the user part and less bugs with harness' MCP settings), The MCP tells the AI that the project variable should be set to the name of the folder of the project. Simple as that. It's been working great on my branch to be honest.

Pretty much my solution involves no work from the user since by default the isolation is set to true and it relies on the AI to decide what the project variable should be set to, which most times it will accurately get right if the instruction is correct. By default, it will set the project variable to the name of the folder of the project. I thought about using other values like the path or a code or a URL but all of them will present issues if you migrate or move the project or involve work from the user having to set those variables which honestly I think is not worth it.

---

(From here, it's written with AI)

Standardized Project Scoping Logic

To ensure a consistent and predictable foundation, I have defined the logic for all four combinations of project isolation (AGENTMEMORY_PROJECT_ISOLATION) and project naming.

Combination	AGENTMEMORY_PROJECT_ISOLATION	Project Name	Logic / Expected Outcome
1	false	Not Passed	Global/Legacy Mode: Memory is treated as global (unscoped), preserving legacy behavior.
2	false	Passed	Global/Legacy Override: When isolation is false, the system ignores the project name and treats memory as global (unscoped).
3	true	Not Passed	Self-Teaching Isolation: System rejects empty input and instructs the AI agent to use the repo root folder basename as the mandatory project name.
4	true	Passed	Strict Scoped Mode: Isolation is true, and the project is explicitly locked to the provided name.

Why this is the right direction:

• Zero-Effort UX: By making AGENTMEMORY_PROJECT_ISOLATION=true the default and having the MCP error message instruct the AI to use the folder basename, I remove the need for manual configuration. The AI learns the expectation instantly via the error feedback loop.
• Data Integrity: I enforce isolation by default, protecting memory from cross-project contamination while still allowing users to opt-out via false if they require legacy, global memory behavior.
• Integration with Issue Resolve project identity from canonical repo URL, not directory basename #716: The proposal in Issue Resolve project identity from canonical repo URL, not directory basename #716 to use the Git remote URL is an excellent "next level" for this identity resolution. In the "Common Case", once Resolve project identity from canonical repo URL, not directory basename #716 is implemented, the MCP could transparently auto-resolve the canonical URL as the project name, further removing the burden from the AI agent to determine the folder name.

Visualization

graph TD
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px;
    classDef highlight fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
    
    Start[Receive Request] --> CheckIsolation{AGENTMEMORY_PROJECT_ISOLATION is true?}
    
    CheckIsolation -- false (It's true by default, so it needs to be explicitaly passed as false. This would be an uncommon case) --> Global[Treat as Global/Unscoped]
    CheckIsolation -- true --> CheckProject{Project Name Passed?}
    
    CheckProject -- true --> Strict[Strictly Scoped by Project Name]
    CheckProject -- false --> TeachAI[Instruct AI to use folder basename, reject if nothing is passed]
    
    Global --> End[Process Request]
    Strict --> End
    TeachAI --> End

    class Global,Strict,TeachAI highlight;

Loading

This model ensures that the "Common Case" creates a self-healing loop where the AI learns the expected project name through standard error feedback, while the other combinations provide predictable global or strict isolation overrides.

[devon3000]

@Durocks if I'm not mistaken, you propose to postpone resolution by the canonical remote URL? That's actually the single most important use case for me, and per @thekoma we agree on the need for this.

I think the emphasis on AGENTMEMORY_PROJECT_NAME may be misplaced. AGENTMEMORY_PROJECT_NAME requires manual configuration, which is less than ideal. I think users shouldn't have to set AGENTMEMORY_PROJECT_NAME at all unless they need to somehow force unification or separation of projects that would otherwise be resolved as the same.

I suspect there are two different user intents at work here, which perhaps suggests two different flags.

AGENTMEMORY_PROJECT_NAME_FROM_REMOTE would resolve the project name from the remote git URL (if available) rather than the local filepath. Personally I think this should default to true although there would be migration issues with that.

AGENTMEMORY_PROJECT_ISOLATION would control whether different clients using the same project name share a single memory system. This should default to false.

[Durocks]

@devon3000 to clarify my position: I believe AGENTMEMORY_PROJECT_ISOLATION (which currently exists in my branch) is fundamentally more critical than AGENTMEMORY_PROJECT_NAME. My experience attempting to configure AGENTMEMORY_PROJECT_NAME across various AI harnesses was friction-heavy; it is significantly more effective to let the AI handle this value dynamically. While manual overrides in MCP settings should remain an option, the system should ideally guide the user via specific error messages if the variable is missing, instructing them on the expected value.

Also, I disagree with the proposal that AGENTMEMORY_PROJECT_ISOLATION should be false by default. It should be true by default for the following reasons:

• Zero-Configuration UX: Most users expect project isolation 99% of the time. By defaulting to true, the system becomes "ready to go" immediately without requiring the user to touch MCP settings.
• Intelligent Fallbacks: If the user hasn't defined the isolation setting, the system should default to true and attempt to auto-resolve the identity—either by inferring it (e.g., folder basename) or by falling back to AGENTMEMORY_PROJECT_NAME if one is explicitly provided.
• Isolation as the Norm: Scenarios where a user desires cross-project memory are rare edge cases. Aligning the default behavior with the common use case ensures a seamless experience for the majority, while still allowing advanced users to opt-out if needed.