Content
<p align="center">
<img src="https://img.shields.io/badge/Go-1.23+-00ADD8?style=for-the-badge&logo=go&logoColor=white" alt="Go">
<img src="https://img.shields.io/badge/PostgreSQL-16+pgvector-4169E1?style=for-the-badge&logo=postgresql&logoColor=white" alt="PostgreSQL">
<img src="https://img.shields.io/badge/MCP-StreamableHTTP-8A2BE2?style=for-the-badge" alt="MCP">
<img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License">
<a href="https://github.com/wqm666/AI-team-know/stargazers"><img src="https://img.shields.io/github/stars/wqm666/AI-team-know?style=for-the-badge" alt="Stars"></a>
</p>
<h1 align="center">Team-Know</h1>
<p align="center">
<strong>Build Your AI-Powered Team Brain — Capture Every Lesson Learned, Never Reinvent the Wheel</strong>
</p>
<p align="center">
<a href="README_zh.md">中文文档</a> · <a href="https://github.com/wqm666/AI-team-know/issues">Report Bug</a> · <a href="https://github.com/wqm666/AI-team-know/issues">Request Feature</a>
</p>
---
## The Problem
AI coding tools are getting incredibly powerful. Yet most teams still haven't achieved the transformative productivity leap they expected.
The bottleneck isn't whether AI can write good code — **it's whether you can feed AI the right context.** When tasks are complex and require domain knowledge, team conventions, and historical decisions, the system's ceiling depends on how well humans can express all of that to AI. That's unstable and inefficient.
**The root cause: expert knowledge isn't being systematically captured, structured, and reused.**
Traditional documentation expects humans to organize knowledge manually. But the most valuable knowledge — the kind that comes from debugging at 2 AM, from that war room incident, from a senior engineer's instinct — is **implicit and unstructured**. It doesn't fit neatly into wikis.
## The Vision: Your Team's Shared Brain
**Team-Know** is a self-hosted team knowledge base that connects AI coding tools (Cursor, Claude Code, etc.) to your team's collective knowledge via the [MCP protocol](https://modelcontextprotocol.io/).
It's not another documentation system. It's **your team's AI-native brain** —
- **Before coding**: AI automatically pulls team standards and known pitfalls
- **During coding**: AI queries domain knowledge and code patterns on demand
- **After coding**: AI captures lessons learned and technical decisions automatically
> When AI becomes the biggest "new hire" on every team, all tacit knowledge must become explicit assets.
> AI can only consume knowledge that's been externalized — what's in your head but not written down is invisible to AI.
## Real-World Impact: From 30 Minutes to 1 Minute
```
Step 1: Engineer A hits a bug and fixes it
└── A spent 30 min in Cursor debugging a tsconfig issue
Step 2: The system captures the lesson automatically
└── After the session, the system detects a "debugging session" (multiple iterations, error messages)
└── LLM extracts the key insight and saves it to the team knowledge base
Step 3: Two weeks later, Engineer B benefits instantly
└── B encounters the same issue
└── AI retrieves the experience from the knowledge base via know_search
└── Not only shows the fix, but adapts it to B's specific configuration
Result: A spent 30 minutes. B spent 1 minute.
```
**This is the power of team knowledge sharing.**
## Key Features
<table>
<tr>
<td width="50%">
### 🧱 Four-Layer Knowledge System
Don't make AI write from scratch — make it **copy and adapt**. Four layers, each with a clear role:
- **Rules** — Team coding standards and hard constraints
- **Patterns** — Copy-paste code skeletons and templates
- **Knowledge** — Lessons learned, debugging tips, technical decisions
- **Specs** — Historical technical designs for reference
</td>
<td width="50%">
### 🏗️ Three-Level Scoping
Knowledge isn't a flat list — it's organized in three levels with automatic inheritance:
- **Global** — Standards shared across all projects
- **Domain** — Conventions shared within a business domain
- **Repository** — Project-specific rules and knowledge
When AI pulls knowledge, all three levels merge automatically. Repo-level takes highest priority.
</td>
</tr>
<tr>
<td width="50%">
### 🔍 Triple-Path Retrieval
Keyword matching, full-text search, and vector semantic search run in parallel — results are intelligently merged and deduplicated.
As your knowledge base grows, vector search discovers semantic connections that keywords miss — like linking "page goes blank" to "component render failure."
</td>
<td width="50%">
### 🤖 Zero-Maintenance Auto-Learning
AI automatically captures knowledge during coding:
- Coding conventions and preferences
- Technical decisions and rationale
- Business patterns and standard implementations
No manual documentation needed. Knowledge flows in naturally from everyday development.
</td>
</tr>
</table>
## The Data Flywheel: Gets Smarter Over Time
```
┌──────────────────────────────────────────────────┐
│ │
│ More usage ──→ Richer data ──→ Smarter AI │
│ ↑ │ │
│ └──────────────────────────────┘ │
│ │
│ The "Data Flywheel" Effect │
│ │
└──────────────────────────────────────────────────┘
```
Every feature delivery enriches the knowledge base:
- Bugs encountered → crystallized into **Knowledge**
- Good implementations → distilled into **Patterns**
- Gaps in standards → added to **Rules**
> Models get replaced. Scaffolding gets thrown away. But team knowledge only compounds.
> **90% copy, 10% write.** That's AI coding's real moat.
## Building a Super Team: Three-Layer Knowledge Architecture
Team-Know is the core layer in a three-tier knowledge system:
| Layer | Name | Content | Goal |
|-------|------|---------|------|
| 1 | **Personal Knowledge** | Business knowledge, learning notes, work experience | Build your AI-powered digital twin |
| 2 | **Team Knowledge** (Team-Know) | Team standards, lessons learned, business conventions | New hires onboard instantly |
| 3 | **AI Coding Tool Layer** | Code standards, templates, API specs | Consume knowledge, produce consistent output |
```
Personal Knowledge ──deposit──→ Team Knowledge ──inject──→ AI Tools
↑ │
└──── Feedback Loop ────┘
```
> You're not investing in scaffolding — you're investing in knowledge assets.
> Your team's code patterns, domain knowledge, and dev standards won't become obsolete when models upgrade.
## Architecture
```
┌────────────────────────────────────────────────────┐
│ AI Clients (Cursor / Claude Code) │
│ ↕ MCP Protocol │
└─────────────────────┬──────────────────────────────┘
│
┌─────────────────────▼──────────────────────────────┐
│ Nginx (:9200) │
│ /web → Frontend /api → Backend /mcp → MCP │
└──┬────────────────┬────────────────────────────────┘
│ │
▼ ▼
Frontend (React) Backend (Go)
│
┌─────┼──────┐
▼ ▼ ▼
Keyword FTS Vector ← Triple-path parallel retrieval
│ │ │
└─────┼──────┘
▼
Orchestrator (merge, deduplicate, rank)
│
▼
PostgreSQL + pgvector
(Global / Domain / Repo storage)
```
## MCP Tools
### Read Tools (AI pulls knowledge)
| Tool | Purpose | Returns |
|------|---------|---------|
| `know_init` | First-time repo registration | Repo status + four-layer knowledge overview |
| `know_update` | Incremental update via git diff | Current four-layer knowledge + timestamps |
| `know_pull` | Pull latest materials to local | Merged standards (three-level inheritance applied) |
| `know_search` | Search domain knowledge | Knowledge entries + relevance scores + source level + action guidance |
### Write Tools (AI contributes knowledge)
| Tool | Purpose | Returns |
|------|---------|---------|
| `know_upload` | Upload materials to server | Update confirmation + new timestamp |
| `know_learn` | Save coding lessons | Knowledge save confirmation + ID + auto status |
| `know_feedback` | Mark knowledge as useful | Feedback confirmation (useful_count + 1) |
| `know_analyze_session` | Extract knowledge at session end | Analysis results + extracted knowledge list |
### Knowledge Review Workflow
The system uses a **Git-like branch protection model** to ensure knowledge quality:
```
AI auto-saves (know_learn / know_analyze_session)
↓ status = "auto" (pending review)
Knowledge stored (not searchable)
↓ Human reviews on Web UI (/web/review)
Approved → status = "approved" → visible to team search
Rejected → status = "rejected" → not searchable
Reverted → status = "auto" → back to review queue
```
Only `approved` knowledge is returned by `know_search`, preventing bad knowledge from spreading.
## Quick Start
### Prerequisites
- Docker + Docker Compose
- Git
### 1. Clone
```bash
git clone https://github.com/wqm666/AI-team-know.git /opt/team-know
cd /opt/team-know
```
### 2. Configure
```bash
cp config.json.example config.json
```
Edit `config.json`:
- Vector search requires a HuggingFace API Key (free: https://huggingface.co/settings/tokens)
- Don't need vector search? Set vector retriever's `enabled` to `false`
### 3. Launch
```bash
docker compose up -d --build
```
### 4. Access
| Service | URL |
|---------|-----|
| Web Dashboard | `http://YOUR_SERVER_IP:9200/web` |
| MCP Endpoint | `http://YOUR_SERVER_IP:9200/mcp` |
| Health Check | `http://YOUR_SERVER_IP:9200/api/health` |
### 5. Update
```bash
bash deploy.sh
```
## Connect Your AI Tools
### Cursor
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"team-know": {
"url": "http://YOUR_SERVER_IP:9200/mcp"
}
}
}
```
### Claude Code
Add to `~/.claude/settings.json`:
```json
{
"mcpServers": {
"team-know": {
"url": "http://YOUR_SERVER_IP:9200/mcp"
}
}
}
```
Once connected, your AI assistant can:
- `know_pull` — Pull team standards before coding
- `know_search` — Search domain knowledge during coding
- `know_learn` — Capture lessons learned after coding
## Local Development
### Backend
```bash
# File mode (no database required)
go run ./cmd/server/
# Listens on :8080 by default
```
### Frontend
```bash
cd web
npm install
npm run dev
# Listens on :5173, proxies API to localhost:8080
```
### With PostgreSQL
```bash
# Start PostgreSQL only
docker compose up -d postgres
# Configure and run backend with PG
cp config.json.example config.json
# Edit config.json: set store.type to "postgres" and configure dsn
go run ./cmd/server/
```
## Retrieval Modes
Three retrievers run in parallel, results merged by the Orchestrator:
| Retriever | Dependency | Capability | Best For |
|-----------|-----------|------------|----------|
| Keyword | None | Exact keyword matching | Always-on fallback |
| FTS | PostgreSQL | Full-text search with tokenization | Knowledge base > 200 entries |
| Vector | PostgreSQL + pgvector + Embedder | Semantic similarity | Knowledge base > 500 entries |
Configuration example (`config.json`):
```json
{
"retrievers": [
{ "type": "keyword", "enabled": true },
{ "type": "fts", "enabled": true },
{
"type": "vector", "enabled": true,
"embedder": { "type": "huggingface", "model": "BAAI/bge-m3", "api_key": "..." }
}
]
}
```
## Project Structure
```
team-know/
├── cmd/server/main.go # Entry point
├── internal/
│ ├── model/ # Data models
│ ├── store/ # Storage layer (FileStore / PgStore)
│ ├── retriever/ # Retrieval layer (Keyword / FTS / Vector + Orchestrator)
│ ├── service/ # Business logic (material merging, formatted output)
│ ├── mcp/ # MCP integration (8 tools)
│ ├── api/ # HTTP API (Web dashboard + review endpoints)
│ ├── config/ # Configuration
│ └── logger/ # Structured logging
├── skills/ # Claude Code Skill system
│ ├── team-know-search/ # Search knowledge (auto-triggered)
│ ├── team-know-learn/ # Save lessons (auto-triggered)
│ ├── team-know-manage/ # Manage knowledge base (init/pull/upload/update)
│ └── team-know-session/ # End-of-session knowledge extraction
├── web/ # React frontend (standalone)
├── docker-compose.yml # One-command deployment
├── Dockerfile # Backend container
├── deploy.sh # Deployment script
├── Makefile # Dev shortcuts
└── config.json.example # Configuration template
```
## Roadmap
- [x] Four-layer knowledge system (Rules / Patterns / Knowledge / Specs)
- [x] Three-level scoping (Global / Domain / Repo) with automatic inheritance
- [x] Triple-path parallel retrieval (Keyword + FTS + Vector)
- [x] 8 MCP tools covering read + write operations
- [x] Auto-learning and experience capture
- [x] Web management dashboard
- [x] Docker one-command deployment
- [ ] Knowledge review workflow (auto → pending → approved)
- [ ] RAG migration (Embedding + LanceDB)
- [ ] Knowledge consumption analytics (recall rate, coverage, usefulness)
- [ ] AI Code Review (diff + rules → review comments)
- [ ] Historical spec archiving and retrieval
- [ ] Personal ↔ Team knowledge bridge
- [ ] Browser extension: one-click knowledge capture
## Contributing
Contributions of all kinds are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Related Projects
- [AI-personal-knows](https://github.com/wqm666/AI-personal-knows) — AI-native personal knowledge base, build your digital twin
- [mcp-go](https://github.com/mark3labs/mcp-go) — MCP protocol implementation in Go
- [pgvector](https://github.com/pgvector/pgvector) — Vector similarity search for PostgreSQL
## Star History
<p align="center">
<a href="https://github.com/wqm666/AI-team-know/stargazers">
<img src="https://starchart.cc/wqm666/AI-team-know.svg?variant=adaptive" alt="Star History Chart" width="600">
</a>
</p>
## License
[MIT](LICENSE) — free to use, fork, and build upon.
---
<p align="center">
<strong>The ceiling of AI coding depends on what you feed it, not how smart it is.</strong>
<br />
<sub>Team-Know — Make team knowledge the real moat of AI coding.</sub>
</p>
