[FEATURE]

[holg]

Problem Statement

Currently Arbor assumes either a monolithic index (everything in one graph) or completely separate indexes per project. This creates friction for developers who work on:

• Related but separate repositories (e.g., a Rust library ecosystem with lib-core, lib-parser, lib-viewer in different directories)
• Multiple unrelated projects where indexing everything together pollutes the graph and slows queries
• Context switching between project groups without re-indexing

The filesystem hierarchy becomes the only way to define "related code," which doesn't reflect how developers actually think about project relationships.

Proposed Solution

Introduce a tagging system that allows logical grouping of indexed projects independent of filesystem structure:

# Index with tags
arbor index --tag lighting      # run in each lighting project
arbor index --tag experimental  # separate experiments
arbor index --tags lighting,oss # multiple tags supported

# Query specific groups
arbor bridge --tag lighting              # only lighting ecosystem
arbor bridge --tags lighting,experimental # combine groups
arbor bridge --exclude-tag experimental  # exclude specific tags

# Manage tags
arbor tags list                          # show all tags and their projects
arbor tags add lighting ./path/to/project
arbor tags remove experimental ./path/to/project

Alternatives Considered

1. Workspace manifest file (arbor-workspace.toml listing project paths) — Less flexible, requires central config file maintenance
2. Symlink-based grouping — Hacky, filesystem-dependent, breaks on Windows
3. Multiple Sled databases — Current workaround, but no cross-group queries possible

Implementation Ideas

• Changes to CLI
  • --tag/--tags flag for arbor index
  • --tag/--tags/--exclude-tag flags for arbor bridge
  • New arbor tags subcommand for tag management
• Changes to visualizer
  • Tag filter dropdown/chips in UI
  • Color-code nodes by tag
• Changes to MCP bridge
  • Pass tag filters to graph queries
  • Expose list_tags as MCP tool
• New language parser — N/A
• Documentation update
  • Usage examples for multi-project workflows
  • Migration guide for existing indexes

Storage schema addition

// arbor-graph/src/metadata.rs
pub struct ProjectMetadata {
    pub root_path: PathBuf,
    pub tags: HashSet<String>,
    pub indexed_at: DateTime<Utc>,
}

// Tag index in Sled: "tag:{tag_name}" -> Vec<project_root_paths>

Additional Context

Real-world use case: I maintain a lighting industry library ecosystem (gldf-rs, l3d-rs, eulumdat-rs, uld-rs) that are logically connected but live in separate repositories. I also work on unrelated projects (acadlisp, portfolio site).

Currently I must either:

• Index everything → bloated graph, irrelevant results when working on one ecosystem
• Maintain separate indexes → lose cross-crate intelligence within the lighting ecosystem

Tags would let me arbor bridge --tag lighting when working on lighting projects, keeping the graph focused while preserving cross-crate edges.

[holg]

Of course i can do the PR for this, but i think it should be discussed first...

[Anandb71]

Thanks for the detailed write-up ,this is a very real problem, and the use case makes complete sense.

You’re right that today Arbor forces a choice between:

• one monolithic graph (noisy, bloated), or
• fully separate indexes (losing cross-crate intelligence)

A logical grouping / tagging layer is a clean way to model how people actually think about related projects, independent of filesystem layout.

That said, this touches core concerns:

• index metadata & persistence
• query filtering semantics
• MCP context guarantees
• CLI + visualizer state

So I don’t want to rush this into the current line.

Plan

• I’m explicitly scoping this to v1.2.5 or 1.2.6 (post-stability cycle)
• I’d like to treat this as a design-first feature, not a quick PR
• Your proposed CLI surface + storage sketch is a great starting point

If you’re up for it, the best next step would be:

• a short design/RFC PR (no implementation yet) covering:
  • tag semantics (index-time vs query-time)
  • how tags interact with world edges
  • guarantees (what tags can/can’t exclude)
  • migration story for existing indexes

Once that’s agreed, I’m very open to you leading or co-leading the implementation.

Really appreciate you bringing a concrete, real-world workflow to the table 👍

[holg]

Thanks for the thoughtful response and for scoping this properly — design-first is absolutely the right approach for something that touches this many layers.

Reflecting on my own use case: my lighting ecosystem plus side projects (acadlisp, portfolio) is probably ~50-100k LOC total. Arbor should handle that fine in a single index, and honestly the "cross-pollination" might even be a feature — surfacing shared patterns I hadn't noticed.

I'll experiment with indexing everything together for a few weeks and see if I actually hit pain points (slow queries, irrelevant context, etc.) rather than speculating. Real friction will inform the RFC better than theory.

That said, the feature becomes essential at scale. Anyone working across multiple large codebases (think browser engines, enterprise monorepos, or consultants jumping between client projects) would hit the monolith-vs-isolation tradeoff hard.
The tagging concept remains valuable — my use case just might not be the one that stress-tests it.

Happy to contribute to the RFC once I have some hands-on data. Will report back with findings.

In the meantime i created another PR, which optionally allows symlink, as my workflow would be to do the arbor-index directory and symlink in there the repositories i want to index

[Anandb71]

Sounds good — thanks for validating this with real usage instead of speculation.

Let’s keep this issue open as a design placeholder until real friction appears at scale.
Once there’s concrete pain (performance, noise, context pollution), we’ll turn that into a focused RFC.

No action planned for the 1.1.x line.

[Anandb71]

Keeping this open as a design placeholder.
The tagging concept is still interesting for multi-project workflows, but Arbor is currently focusing on stability and workflow features (diff/check/index improvements).
Once real friction appears at scale (large multi-repo environments), we can revisit this as an RFC for a future release.
For now no implementation is planned in the v1.x line.