The problem
In a monorepo, each package has its own context. Your AI assistant in packages/api doesn't know about patterns documented in packages/shared. You end up re-explaining the same conventions in every session.
Set Up the Shared Source
Create a shared Knowns project with your team's docs:
cd packages/shared
knowns init
knowns doc create "API conventions" \
--folder patterns \
--content "## API Conventions\n\n- Use REST with JSON\n- Always return { data, error, meta }"
knowns doc create "Error handling" \
--folder patterns \
--content "## Error Handling\n\n- Use custom AppError class\n- Always include error code"
monorepo/ ├── packages/ │ ├── shared/ │ │ └── .knowns/ │ │ └── docs/ │ │ └── patterns/ │ │ ├── api-conventions.md │ │ └── error-handling.md │ ├── api/ │ │ └── .knowns/ ← will import from shared │ └── web/ │ └── .knowns/ ← will import from shared
Configure Imports in Consumer Packages
In each package that needs the shared docs, edit .knowns/config.json:
{
"imports": [
{
"name": "shared-patterns",
"source": "../shared/.knowns/docs",
"type": "local",
"include": ["patterns/**"]
}
]
}
Cross-repo imports
For separate repos, use Git or npm sources:
{
"imports": [
{
"name": "team-standards",
"source": "https://github.com/your-org/standards.git",
"type": "git",
"path": ".knowns/docs",
"include": ["patterns/**"]
}
]
}
Sync
knowns sync
Syncing shared-patterns... ✓ Imported patterns/api-conventions.md ✓ Imported patterns/error-handling.md 2 docs synced
Imported docs appear in .knowns/imports/ and are available to AI via MCP and search.
Use Shared Context
Now when your AI works in packages/api, it has access to shared patterns:
You: Create an endpoint following our API conventions
AI: [Reads @doc/patterns/api-conventions via MCP]
I see your conventions require:
- REST with JSON responses
- { data, error, meta } response shape
- Correct HTTP status codes
Creating the endpoint...Share Templates Too
Templates can also be shared:
cd packages/shared
knowns template create api-endpoint \
--description "Standard REST endpoint with error handling"
Consumer packages import and use them:
cd packages/api
knowns sync
knowns template run api-endpoint --name users
Keeping Things in Sync
Auto-sync on init
Add to your workflow — run sync at session start:
knowns sync && knowns init
Selective Imports
Use include and exclude patterns to control what gets imported:
{
"imports": [
{
"name": "shared",
"source": "../shared/.knowns/docs",
"type": "local",
"include": ["patterns/**"],
"exclude": ["patterns/internal/**"]
}
]
}
Key Takeaways
| Without shared knowledge | With Knowns imports |
|---|---|
| Re-explain conventions in every package | Document once, share everywhere |
| AI doesn't know about shared patterns | Imported docs are searchable via MCP |
| Manual copy-paste of templates | Sync from local, Git, or npm sources |
| All-or-nothing sharing | Selective import with include/exclude |
What's next?
Read the Import System docs for the full reference, or check out Templates for code generation patterns.
Vấn đề
Trong monorepo, mỗi package có context riêng. AI assistant trong packages/api không biết về patterns documented trong packages/shared. Bạn phải giải thích lại conventions mỗi session.
Setup Shared Source
Tạo shared Knowns project với docs của team:
cd packages/shared
knowns init
knowns doc create "API conventions" \
--folder patterns \
--content "## API Conventions\n\n- Dùng REST với JSON\n- Luôn trả về { data, error, meta }"
knowns doc create "Error handling" \
--folder patterns \
--content "## Error Handling\n\n- Dùng custom AppError class\n- Luôn bao gồm error code"
monorepo/ ├── packages/ │ ├── shared/ │ │ └── .knowns/ │ │ └── docs/ │ │ └── patterns/ │ │ ├── api-conventions.md │ │ └── error-handling.md │ ├── api/ │ │ └── .knowns/ ← sẽ import từ shared │ └── web/ │ └── .knowns/ ← sẽ import từ shared
Cấu hình Imports trong Consumer Packages
Trong mỗi package cần shared docs, edit .knowns/config.json:
{
"imports": [
{
"name": "shared-patterns",
"source": "../shared/.knowns/docs",
"type": "local",
"include": ["patterns/**"]
}
]
}
Cross-repo imports
Cho repos riêng biệt, dùng Git hoặc npm sources:
{
"imports": [
{
"name": "team-standards",
"source": "https://github.com/your-org/standards.git",
"type": "git",
"path": ".knowns/docs",
"include": ["patterns/**"]
}
]
}
Sync
knowns sync
Syncing shared-patterns... ✓ Imported patterns/api-conventions.md ✓ Imported patterns/error-handling.md 2 docs synced
Docs imported xuất hiện trong .knowns/imports/ và available cho AI qua MCP và search.
Dùng Shared Context
Giờ khi AI làm việc trong packages/api, nó có access tới shared patterns:
Bạn: Tạo endpoint theo API conventions của mình
AI: [Đọc @doc/patterns/api-conventions qua MCP]
Tôi thấy conventions yêu cầu:
- REST với JSON responses
- { data, error, meta } response shape
- HTTP status codes đúng
Đang tạo endpoint...Share Templates luôn
Templates cũng có thể shared:
cd packages/shared
knowns template create api-endpoint \
--description "Standard REST endpoint with error handling"
Consumer packages import và dùng:
cd packages/api
knowns sync
knowns template run api-endpoint --name users
Giữ đồng bộ
Auto-sync khi init
Thêm vào workflow — chạy sync khi bắt đầu session:
knowns sync && knowns init
Selective Imports
Dùng include và exclude patterns để kiểm soát import:
{
"imports": [
{
"name": "shared",
"source": "../shared/.knowns/docs",
"type": "local",
"include": ["patterns/**"],
"exclude": ["patterns/internal/**"]
}
]
}
Điểm chính
| Không có shared knowledge | Với Knowns imports |
|---|---|
| Giải thích lại conventions trong mỗi package | Document một lần, share mọi nơi |
| AI không biết shared patterns | Imported docs searchable qua MCP |
| Copy-paste templates thủ công | Sync từ local, Git, hoặc npm sources |
| Chia sẻ tất-cả-hoặc-không | Selective import với include/exclude |
Tiếp theo?
Đọc Import System docs cho reference đầy đủ, hoặc xem Templates cho code generation patterns.