Repo A has knowledge

Repo B imports from A via SSH

knowns import sync

AI in B reads A's context

The scenario

Your team has separate private repos — backend-api, mobile-app, web-frontend. Each has its own Knowns docs: API contracts, conventions, patterns. When you're working in the mobile repo and need to understand the backend's auth flow, your AI has no idea — it can only see the current repo.

The Solution

Import one repo's knowledge into another. That's it.

# In mobile-app, import backend-api's knowledge
knowns import git@your-server:your-org/backend-api.git \
  --name backend \
  --include ".knowns/docs/**"

Now your mobile AI can read the backend's API contract, auth flow, error codes — without leaving the mobile repo.

Each Repo Already Has Its Own Knowledge

Each repo uses Knowns independently. They already have docs, memory, and patterns from daily work:

File structure

backend-api/.knowns/docs/
├── specs/
│   └── user-auth.md          ← JWT auth spec
├── patterns/
│   ├── error-handling.md     ← error codes, AppError class
│   └── api-response.md      ← { data, error, meta } format
└── architecture/
  └── overview.md           ← Express + Prisma + PostgreSQL

File structure

mobile-app/.knowns/docs/
├── patterns/
│   ├── mvvm.md               ← MVVM architecture
│   └── offline-sync.md       ← offline queue + sync
└── conventions/
  └── secure-storage.md     ← Keychain/Keystore usage

File structure

web-frontend/.knowns/docs/
├── patterns/
│   ├── state-management.md   ← Zustand + React Query
│   └── api-client.md         ← auto-refresh, retry logic
└── conventions/
  └── component-structure.md

No central repo needed. Each repo's knowledge grows naturally as the team works.

Import One Repo into Another

When you need cross-repo context, just import:

Mobile needs backend's API docs:

cd mobile-app
knowns import git@your-server:your-org/backend-api.git \
  --name backend \
  --include ".knowns/docs/**"

Frontend needs backend's API docs too:

cd web-frontend
knowns import git@your-server:your-org/backend-api.git \
  --name backend \
  --include ".knowns/docs/**"

Backend needs to understand mobile's offline patterns:

cd backend-api
knowns import git@your-server:your-org/mobile-app.git \
  --name mobile \
  --include ".knowns/docs/patterns/**"

SSH is required for private repos

Knowns uses SSH for Git imports — there's no built-in GitHub/GitLab token auth. Make sure your SSH key has read access to the source repo. Works with any Git host (GitHub, GitLab, Bitbucket, self-hosted). For CI/CD, use deploy keys.

Sync to pull the docs:

knowns import sync

Sync in mobile-app

Syncing backend...
✓ Imported .knowns/docs/specs/user-auth.md
✓ Imported .knowns/docs/patterns/error-handling.md
✓ Imported .knowns/docs/patterns/api-response.md
✓ Imported .knowns/docs/architecture/overview.md
4 docs synced from backend-api

AI Reads Cross-Repo Context

Now your AI assistant in the mobile repo understands the backend:

In mobile-app

You: Implement the login screen that calls the backend auth API

AI:  [Reads @doc/imports/backend/specs/user-auth]
   [Reads @doc/imports/backend/patterns/api-response]
   [Reads @doc/patterns/mvvm]
   [Reads @doc/conventions/secure-storage]

   From the backend spec:
   - POST /auth/login returns { accessToken, refreshToken }
   - Error format: { data: null, error: { code, message } }

   Following mobile conventions:
   - MVVM: LoginViewModel calls AuthRepository
   - Store tokens in Keychain (iOS) / Keystore (Android)

   Creating src/features/auth/LoginViewModel.kt...

The AI combines the backend's API contract with the mobile's own patterns — without you explaining anything.

Stay Up to Date

When the backend team updates their API docs, one command pulls the changes:

cd mobile-app
knowns import sync

Sync picks up changes

Syncing backend...
✓ Updated .knowns/docs/specs/user-auth.md (changed)
· .knowns/docs/patterns/error-handling.md (unchanged)
· .knowns/docs/patterns/api-response.md (unchanged)
· .knowns/docs/architecture/overview.md (unchanged)
1 doc updated

Filter What You Import

You don't have to import everything. Use include and exclude:

# Only import API specs, not internal architecture docs
knowns import git@your-server:your-org/backend-api.git \
  --name backend \
  --include ".knowns/docs/specs/**" ".knowns/docs/patterns/**" \
  --exclude ".knowns/docs/architecture/**"

Or pin to a specific branch/tag:

knowns import git@your-server:your-org/backend-api.git \
  --name backend \
  --include ".knowns/docs/**" \
  --ref v2.0.0

Example: 3 Repos Importing from Each Other

# mobile-app imports backend's API docs
knowns import git@your-server:your-org/backend-api.git \
  --name backend --include ".knowns/docs/**"

# web-frontend imports backend's API docs
knowns import git@your-server:your-org/backend-api.git \
  --name backend --include ".knowns/docs/**"

# backend imports mobile's offline patterns (to understand client behavior)
knowns import git@your-server:your-org/mobile-app.git \
  --name mobile --include ".knowns/docs/patterns/**"

Each repo keeps its own knowledge and pulls what it needs from others. No central repo, no shared conventions file, no overhead.

Before vs After

Before	After
Mobile dev asks 'what's the auth response format?' on Slack	AI reads it from imported backend docs
Frontend dev reads backend README for error codes	knowns import sync — error codes are in context
Backend changes API → mobile breaks next sprint	Backend updates docs → mobile syncs → AI knows
Each repo's AI only sees its own code	Each repo's AI sees its own + imported knowledge
Cross-repo context lives in people's heads	Cross-repo context lives in imported docs

Tips

Import is one-directional

Importing backend into mobile doesn't change the backend repo. It's read-only — you're pulling a copy of their docs into your .knowns/imports/ folder.

Sync regularly

Run knowns import sync at the start of each session or add it to CI:

steps:
  - name: Sync cross-repo knowledge
    run: knowns import sync --force

Start with one import

Don't import everything from everywhere. Start with the one cross-repo dependency that causes the most friction — usually the API contract between backend and clients.

What's next?

See Monorepo Knowledge Sharing for the local-folder variant, or read the Import System docs for the full reference.

Repo A có knowledge

Repo B import từ A qua SSH

knowns import sync

AI trong B đọc context của A

Tình huống

Team bạn có các private repos riêng biệt — backend-api, mobile-app, web-frontend. Mỗi repo có Knowns docs riêng: API contracts, conventions, patterns. Khi bạn đang làm việc trong mobile repo và cần hiểu auth flow của backend, AI không biết gì — nó chỉ thấy repo hiện tại.

Giải pháp

Import knowledge từ repo này sang repo kia. Vậy thôi.

# Trong mobile-app, import knowledge của backend-api
knowns import git@your-server:your-org/backend-api.git \
  --name backend \
  --include ".knowns/docs/**"

Giờ AI trong mobile có thể đọc API contract, auth flow, error codes của backend — mà không cần rời mobile repo.

Mỗi Repo Đã Có Knowledge Riêng

Mỗi repo dùng Knowns độc lập. Chúng đã có docs, memory, và patterns từ công việc hàng ngày:

File structure

backend-api/.knowns/docs/
├── specs/
│   └── user-auth.md          ← JWT auth spec
├── patterns/
│   ├── error-handling.md     ← error codes, AppError class
│   └── api-response.md      ← { data, error, meta } format
└── architecture/
  └── overview.md           ← Express + Prisma + PostgreSQL

File structure

mobile-app/.knowns/docs/
├── patterns/
│   ├── mvvm.md               ← MVVM architecture
│   └── offline-sync.md       ← offline queue + sync
└── conventions/
  └── secure-storage.md     ← Keychain/Keystore usage

File structure

web-frontend/.knowns/docs/
├── patterns/
│   ├── state-management.md   ← Zustand + React Query
│   └── api-client.md         ← auto-refresh, retry logic
└── conventions/
  └── component-structure.md

Không cần central repo. Knowledge của mỗi repo tự lớn lên khi team làm việc.

Import Repo Này vào Repo Kia

Khi cần cross-repo context, chỉ cần import:

Mobile cần API docs của backend:

cd mobile-app
knowns import git@your-server:your-org/backend-api.git \
  --name backend \
  --include ".knowns/docs/**"

Frontend cũng cần API docs của backend:

cd web-frontend
knowns import git@your-server:your-org/backend-api.git \
  --name backend \
  --include ".knowns/docs/**"

Backend cần hiểu offline patterns của mobile:

cd backend-api
knowns import git@your-server:your-org/mobile-app.git \
  --name mobile \
  --include ".knowns/docs/patterns/**"

SSH bắt buộc cho private repos

Knowns dùng SSH cho Git imports — không có built-in GitHub/GitLab token auth. Đảm bảo SSH key có read access tới source repo. Hoạt động với mọi Git host (GitHub, GitLab, Bitbucket, self-hosted). Cho CI/CD, dùng deploy keys.

Sync để pull docs:

knowns import sync

Sync trong mobile-app

Syncing backend...
✓ Imported .knowns/docs/specs/user-auth.md
✓ Imported .knowns/docs/patterns/error-handling.md
✓ Imported .knowns/docs/patterns/api-response.md
✓ Imported .knowns/docs/architecture/overview.md
4 docs synced from backend-api

AI Đọc Cross-Repo Context

Giờ AI assistant trong mobile repo hiểu backend:

Trong mobile-app

You: Implement màn hình login gọi backend auth API

AI:  [Reads @doc/imports/backend/specs/user-auth]
   [Reads @doc/imports/backend/patterns/api-response]
   [Reads @doc/patterns/mvvm]
   [Reads @doc/conventions/secure-storage]

   Từ backend spec:
   - POST /auth/login trả { accessToken, refreshToken }
   - Error format: { data: null, error: { code, message } }

   Theo mobile conventions:
   - MVVM: LoginViewModel gọi AuthRepository
   - Lưu tokens trong Keychain (iOS) / Keystore (Android)

   Đang tạo src/features/auth/LoginViewModel.kt...

AI kết hợp API contract của backend với patterns riêng của mobile — mà bạn không cần giải thích gì.

Cập nhật nhanh

Khi backend team update API docs, một lệnh là xong:

cd mobile-app
knowns import sync

Sync nhận thay đổi

Syncing backend...
✓ Updated .knowns/docs/specs/user-auth.md (changed)
· .knowns/docs/patterns/error-handling.md (unchanged)
· .knowns/docs/patterns/api-response.md (unchanged)
· .knowns/docs/architecture/overview.md (unchanged)
1 doc updated

Lọc những gì cần import

Không cần import hết. Dùng include và exclude:

# Chỉ import API specs, không lấy internal architecture docs
knowns import git@your-server:your-org/backend-api.git \
  --name backend \
  --include ".knowns/docs/specs/**" ".knowns/docs/patterns/**" \
  --exclude ".knowns/docs/architecture/**"

Hoặc pin vào branch/tag cụ thể:

knowns import git@your-server:your-org/backend-api.git \
  --name backend \
  --include ".knowns/docs/**" \
  --ref v2.0.0

Ví dụ: 3 Repos Import lẫn nhau

# mobile-app import API docs của backend
knowns import git@your-server:your-org/backend-api.git \
  --name backend --include ".knowns/docs/**"

# web-frontend import API docs của backend
knowns import git@your-server:your-org/backend-api.git \
  --name backend --include ".knowns/docs/**"

# backend import offline patterns của mobile (để hiểu client behavior)
knowns import git@your-server:your-org/mobile-app.git \
  --name mobile --include ".knowns/docs/patterns/**"

Mỗi repo giữ knowledge riêng và pull những gì cần từ repo khác. Không central repo, không shared conventions file, không overhead.

Trước vs Sau

Trước	Sau
Mobile dev hỏi 'auth response format là gì?' trên Slack	AI đọc từ imported backend docs
Frontend dev đọc backend README để tìm error codes	knowns import sync — error codes có sẵn trong context
Backend đổi API → mobile break sprint sau	Backend update docs → mobile sync → AI biết
AI mỗi repo chỉ thấy code của nó	AI mỗi repo thấy knowledge của nó + imported knowledge
Cross-repo context nằm trong đầu người	Cross-repo context nằm trong imported docs

Tips

Import là một chiều

Import backend vào mobile không thay đổi gì ở backend repo. Nó read-only — bạn đang pull bản copy docs của họ vào .knowns/imports/ của bạn.

Sync thường xuyên

Chạy knowns import sync đầu mỗi session hoặc thêm vào CI:

steps:
  - name: Sync cross-repo knowledge
    run: knowns import sync --force

Bắt đầu với một import

Đừng import hết mọi thứ từ mọi nơi. Bắt đầu với cross-repo dependency gây friction nhiều nhất — thường là API contract giữa backend và clients.

Xem Monorepo Knowledge Sharing cho variant local-folder, hoặc đọc Import System docs để xem full reference.

Private Repo Knowledge Sharing

The Solution

Each Repo Already Has Its Own Knowledge

Import One Repo into Another

AI Reads Cross-Repo Context

Stay Up to Date

Filter What You Import

Example: 3 Repos Importing from Each Other

Before vs After

Tips

Giải pháp

Mỗi Repo Đã Có Knowledge Riêng

Import Repo Này vào Repo Kia

AI Đọc Cross-Repo Context

Cập nhật nhanh

Lọc những gì cần import

Ví dụ: 3 Repos Import lẫn nhau

Trước vs Sau

Tips

Related articles

Monorepo Knowledge Sharing