# How the Source Fetcher Registry Handles Git and Local File Protocols in TencentDB-Agent-Memory

> Learn how the Source Fetcher Registry in TencentDB-Agent-Memory manages Git and local file protocols. Discover its automatic classification and routing for efficient source fetching.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-26

---

**The `SourceFetcherRegistry` class in [`src/source-fetcher/registry.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/source-fetcher/registry.ts) automatically classifies source URLs by protocol scheme and routes them to registered fetcher implementations, currently supporting Git repositories while preparing for local file system support.**

The **Source Fetcher Registry** serves as the central routing layer in the TencentDB-Agent-Memory project, abstracting protocol complexity from the knowledge module. By analyzing URL patterns in `detectType()` and maintaining an internal registry of fetcher implementations, the system decouples protocol detection from retrieval logic, allowing [`module.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/module.ts) to fetch code without handling protocol-specific details.

## Protocol Detection in the Registry

The registry's private `detectType()` method implements URL scheme analysis to classify incoming source strings into three categories: **git**, **local**, and **ftp**.

### Git URL Patterns

URLs beginning with version control prefixes are mapped to the **git** type:

- `git@` (SSH Git protocol)
- `ssh://` (SSH URL scheme)
- `https://` or `http://` (HTTP-based Git)

The detection logic uses simple string prefix matching:

```ts
// src/source-fetcher/registry.ts
private detectType(url: string): SourceType {
  if (url.startsWith("git@") || url.startsWith("ssh://") ||
      url.startsWith("https://") || url.startsWith("http://")) {
    return "git";
  }
  if (url.startsWith("file://") || url.startsWith("/") || url.startsWith("./")) {
    return "local";
  }
  if (url.startsWith("ftp://")) return "ftp";
  return "git";
}

```

### Local File Path Recognition

The registry recognizes local filesystem paths through three distinct patterns:

- `file://` (Explicit file protocol)
- `/` (Absolute Unix paths)
- `./` (Relative paths)

### Fallback Strategy

Unrecognized URL patterns default to the **git** type, ensuring backwards compatibility while maintaining strict type safety through the `SourceType` union type defined in [`src/source-fetcher/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/source-fetcher/types.ts).

## Git Protocol Implementation

The **GitSourceFetcher** class in [`src/source-fetcher/git-fetcher.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/source-fetcher/git-fetcher.ts) provides the concrete implementation for Git URLs. This fetcher leverages the **simple-git** library to perform repository operations.

### Shallow Cloning and Syncing

The `GitSourceFetcher` implements two primary operations:

1. **`fetch()`** – Performs shallow clones to minimize bandwidth and storage
2. **`sync()`** – Handles incremental updates to existing repositories

### Security Validation

Before executing Git operations, the fetcher validates that the target URL is a public HTTPS repository. The implementation includes **SSRF (Server-Side Request Forgery)** protection by optionally blocking private and loopback addresses, ensuring the agent cannot be tricked into accessing internal network resources.

```ts
// Usage pattern from src/module.ts
const registry = new SourceFetcherRegistry();
const fetcher = registry.resolve("https://github.com/TencentCloud/TencentDB-Agent-Memory.git");
await fetcher.fetch(repoUrl, branch, destinationPath);

```

## Local File Protocol Support

While the registry can **detect** local file protocols, the concrete implementation remains a planned extension. The current codebase in [`src/source-fetcher/registry.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/source-fetcher/registry.ts) registers only the `GitSourceFetcher` in its constructor:

```ts
// src/source-fetcher/registry.ts
constructor() {
  this.register(new GitSourceFetcher());
  // Future: this.register(new LocalSourceFetcher());
  // Future: this.register(new FtpSourceFetcher());
}

```

### Future LocalSourceFetcher Architecture

When implemented, a **LocalSourceFetcher** class will follow the same `ISourceFetcher` interface defined in [`src/source-fetcher/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/source-fetcher/types.ts). It will handle `file://` URLs and filesystem paths by copying or reading local source files directly, bypassing network operations entirely.

The registry's design ensures that once `LocalSourceFetcher` is registered via `registry.register(new LocalSourceFetcher())`, the existing `detectType()` logic will automatically route local paths to this implementation without modifying consumer code in [`module.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/module.ts).

## Fetcher Resolution Workflow

The `resolve()` method orchestrates the complete routing pipeline:

```ts
// src/source-fetcher/registry.ts
resolve(sourceUrl: string): ISourceFetcher {
  const type = this.detectType(sourceUrl);
  const fetcher = this.fetchers.get(type);
  if (!fetcher) {
    throw new Error(`unsupported source type: ${type} (${sourceUrl})`);
  }
  return fetcher;
}

```

This method executes three distinct steps:

1. **Classification** – Calls `detectType()` to determine the `SourceType`
2. **Lookup** – Retrieves the matching fetcher from the internal `Map<SourceType, ISourceFetcher>`
3. **Validation** – Throws an explicit error if no fetcher exists for the detected type

The error handling prevents runtime failures when encountering unimplemented protocols (such as `ftp://` or `local` files in the current release).

## Summary

- The **Source Fetcher Registry** in [`src/source-fetcher/registry.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/source-fetcher/registry.ts) uses prefix-based pattern matching in `detectType()` to classify URLs as **git**, **local**, or **ftp** protocols.
- **Git URLs** (including SSH and HTTP variants) route to **GitSourceFetcher**, which uses simple-git for shallow clones and includes SSRF protection.
- **Local file paths** (starting with `file://`, `/`, or `./`) are recognized but currently throw errors until `LocalSourceFetcher` is implemented.
- The **resolve()** method provides a unified interface that returns protocol-specific fetchers, allowing [`module.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/module.ts) to remain agnostic to source retrieval mechanisms.
- New fetcher implementations can be added via `registry.register()` without modifying existing detection logic.

## Frequently Asked Questions

### How does the Source Fetcher Registry distinguish between Git and local file sources?

The registry examines URL prefixes in the private `detectType()` method. URLs starting with `git@`, `ssh://`, `https://`, or `http://` map to the **git** type, while those beginning with `file://`, `/`, or `./` map to **local**. Any unrecognized pattern falls back to **git** as the default type.

### What happens when I try to fetch a local file URL in the current version?

The registry will detect the **local** type via `detectType()`, but the `resolve()` method will throw an error stating `unsupported source type: local` because only `GitSourceFetcher` is registered in the constructor. Support for local files requires implementing and registering a `LocalSourceFetcher` class.

### How does the GitSourceFetcher protect against SSRF attacks?

The `GitSourceFetcher` in [`src/source-fetcher/git-fetcher.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/source-fetcher/git-fetcher.ts) validates that target URLs point to public HTTPS repositories before cloning. It optionally blocks private IP ranges and loopback addresses, preventing the agent from accessing internal network resources through malicious repository URLs.

### Can I add support for additional protocols like FTP?

Yes. Implement the `ISourceFetcher` interface from [`src/source-fetcher/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/source-fetcher/types.ts), update `detectType()` to recognize your protocol prefix (such as `ftp://`), then register the instance using `registry.register(new FtpSourceFetcher())`. The existing resolution logic will automatically route matching URLs to your implementation.