Content
<div align="center">
# Memforge
**Empowering AI-powered development with team memory — coding gets better, teams get stronger**
> **Disclaimer**: This project is released for learning and reference purposes only. It does not represent any company's production system. Use at your own risk.
*Engineering Intelligence Platform for AI-Powered Development*
[](LICENSE)
[](https://nodejs.org)
[](https://postgresql.org)
[](https://github.com/pgvector/pgvector)
[Quick Start](#quick-start) · [Features](#features) · [Architecture](#architecture) · [MCP Tools](#mcp-tools) · [Deployment Guide](docs/deployment-guide.md) · [MCI Deployment](docs/deployment-mci.md) · [User Guide](docs/user-guide.md) · [Environment Variables](docs/configuration.md)
</div>
---
## What is Memforge?
Memforge is an engineering intelligence platform based on the Model Context Protocol (MCP). It enables AI-powered coding assistants like Cursor and Claude Code to possess **persistent memory across sessions**, **team coding standards awareness**, and **microservices architecture cognition**.
**AI without Memforge:**
- Each conversation starts from scratch, without recalling previous architecture decisions
- Unaware of team coding standards and forbidden coding practices
- Ignorant of downstream services and their dependencies
**AI with Memforge:**
- Automatically retrieves relevant historical experiences and standards before making code changes
- Automatically precipitates bug fixes into the team's knowledge base
- Understands service topology and proactively alerts about upstream impacts when modifying interfaces
### Workflow Demonstration
```
# 1. Fixing a Bug — AI remembers automatically
store_memory({
title: "Redis connection pool exhaustion: maxConnections default value too small",
content: "Symptoms: TimeoutError after 5000ms...",
scope: "bug_pattern",
visibility: "product_line"
})
→ ✓ Stored, automatically vectorized, duplicate detected, and rule candidates associated
# 2. Encountering similar issues next time — AI recalls automatically
recall_memory({ query: "Redis connection timeout", product_line: "myteam" })
→ [1] Redis connection pool exhaustion: maxConnections default value too small (similarity 0.94)
Fixing solution: Change DB_POOL_MAX from default 10 to 50...
# 3. Elevating patterns to team standards
propose_rule({
title: "External connections must explicitly set connection pool limits",
rule_type: "infra",
severity: "error"
})
→ ✓ Rule candidate created, waiting for lead/admin voting and activation
→ ✓ Activated and automatically synchronized to .cursor/rules/memforge-rules.mdc
```
---
## Features
### Memory System
- **Semantic Search**: Based on pgvector HNSW index, millisecond-level semantic recall
- **Four-layer Visibility**: Personal → Team → Product Line → Global cascading query
- **Branch Guard**: Batch indexing and Code Review automatically filter non-default branches to ensure the knowledge base only contains master/main code
- **Sensitive Protection**: Automatically detects and rejects API Key / Token / PII before ingestion
### Automatic Learning
- **Document Indexing**: Scans `docs/` directory, splits documents into semantic paragraphs, and ingests them in bulk
- **Commit Learning**: Analyzes Git history, extracts bug fixes, refactoring, and performance optimization knowledge
- **Code Review Extraction**: Automatically summarizes team coding standards from Review comments
- **Real-time Monitoring**: Automatically triggers incremental indexing upon file changes
### Standard Engine
- **Rule Proposal**: AI automatically discovers and proposes candidate standards with conflict detection
- **Weighted Voting**: Admin / Lead / Developer three-level voting weights
- **Automatic Synchronization**: Activated standards are automatically synchronized to Cursor `.mdc` rule files
- **Effect Measurement**: Tracks standard application times and violation events
### Topology Awareness
- **Automatic Scanning**: Built-in scanning engine supports 15+ language/framework dependency detection
- **Call Chain Query**: Queries service upstream and downstream call relationships
- **Change Impact Analysis**: Automatically analyzes upstream impact scope before modifying interfaces
- **Release Order Deduction**: Topology sorting generates correct multi-service release order
### Knowledge Base Management
- **Structured Knowledge**: 7 types of knowledge (FAQ / Operation Guide / Troubleshooting Guide / Technical Document / Fault Case / SOP / API Reference)
- **Hybrid Search**: BM25 + Vector Search + RRF fusion ranking, bilingual full-text indexing (English stemming + Chinese word segmentation)
- **Confidence Scoring**: Four-factor confidence score combining retrieval score, user feedback, and expert review
- **Compilation and Review Workflow**: Draft → Published → Archived state management with audit tracking
- **Ticket Import**: Batch import customer service tickets, automatically converting them into knowledge entries
- **Feedback Loop**: Helpful / Unhelpful feedback directly affects search ranking
### Team Collaboration
- **MCP Gateway**: OAuth 2.1 + PKCE + RBAC, supporting multi-users
- **Product Line Isolation**: Multi-team / multi-product line data isolation with permission filtering
- **Web UI**: Vue 3 management panel with visualized memory, standards, topology, and knowledge base
- **Audit Log**: All operations are traceable
---
## Quick Start
### Prerequisites
- Node.js 20+
- PostgreSQL 15+ with [pgvector](https://github.com/pgvector/pgvector)
- Embedding service compatible with OpenAI `/v1/embeddings` protocol (recommended [SiliconFlow](https://siliconflow.cn) + BGE-M3, free quota sufficient)
### Step 1: Installation
```bash
# macOS installation
brew install postgresql@17 pgvector redis ripgrep
# Initialize database
createuser memforge && createdb -O memforge memforge
psql -U memforge -d memforge -f sql/init.sql
# Install dependencies & build
git clone https://github.com/zql0805/memforge.git
cd memforge
npm install && npm run build
```
> **About ripgrep**: Runtime dependency for `scan_topology` topology scanning engine. Still usable without it, but RPC call chains cannot be detected (only Maven/npm level SDK dependencies).
### Step 2: Configure Embedding
Configure in `.env` (copy `.env.example` and modify):
```bash
DATABASE_URL=postgresql://memforge:memforge_dev@localhost:5432/memforge
OPENAI_BASE_URL=https://api.siliconflow.cn/v1
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_EMBEDDING_MODEL=BAAI/bge-m3
```
### Step 3: Configure Cursor MCP
Add in `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"memforge": {
"command": "node",
"args": ["/path/to/memforge/packages/memory-service/dist/index.js"],
"env": {
"DATABASE_URL": "postgresql://memforge:memforge_dev@localhost:5432/memforge",
"OPENAI_BASE_URL": "https://api.siliconflow.cn/v1",
"OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx",
"OPENAI_EMBEDDING_MODEL": "BAAI/bge-m3"
}
},
"memforge-rules": {
"command": "node",
"args": ["/path/to/memforge/packages/rules-engine/dist/index.js"],
"env": {
"DATABASE_URL": "postgresql://memforge:memforge_dev@localhost:5432/memforge",
"OPENAI_BASE_URL": "https://api.siliconflow.cn/v1",
"OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx",
"OPENAI_EMBEDDING_MODEL": "BAAI/bge-m3"
}
}
}
}
```
### Step 4: Cold Start
Restart Cursor and execute in the dialog:
```
Help me bootstrap and import existing knowledge assets
```
Memforge will automatically install Cursor Rules and guide you through the initial setup.
---
## Docker Compose Quick Start (Team Mode)
```bash
# Copy configuration
cp .env.example .env
# Edit .env, fill in JWT_SECRET and Embedding configuration
# Start complete service stack (PostgreSQL + Redis + Gateway + Memory + Rules + Web UI)
docker compose --profile gateway up -d
# Check status
docker compose ps
```
Default Web UI access address: `http://localhost` (Nginx port 80)
---
## Architecture
```
┌─────────────────────────────────────────────────────┐
│ AI-powered coding assistant │
│ (Cursor / Claude Code / VS Code) │
└──────────────────┬──────────────────────────────────┘
│ MCP Protocol
┌─────────┴──────────┐
│ Memforge Gateway │ OAuth 2.1 + RBAC + audit
│ (Port 3000) │
└──┬──────────┬────┬─┘
│ │ │
┌─────────┴──┐ ┌───┴────┴────┐ ┌──────────────┐
│ Memory │ │ Rules │ │ Knowledge │
│ Service │ │ Engine │ │ Service │
│ (Port 3001)│ │ (Port 3002) │ │ (Port 3003) │
└────┬───────┘ └──────┬──────┘ └──────┬───────┘
│ │ │
┌────┴─────────────────┴─────────────────┴──┐
│ PostgreSQL + pgvector │
│ (memory / standards / knowledge base / topology / audit) │
└────────────────────────────────────────────┘
│
┌────┴──────┐
│ Redis │ L2 cache (optional)
└───────────┘
```
**Stand-alone Mode** (personal developer): Memory Service + Rules Engine directly connect to Cursor via stdio, without Gateway. Knowledge Service only supports HTTP mode and can be accessed locally after starting.
**Team Mode**: Unified authentication through Gateway, multi-user shared memory base, and product line data isolation.
---
## Web UI Preview
> Access `http://localhost` (or your service address, default port 80) after deployment
| Memory Management | Standard Management | Topology Visualization |
|---|---|---|
| Search, filter, and review full memory | Propose / vote / activate coding standards | Service call chain visualization |
## MCP Tools
<details>
<summary><b>Memory Service（48 tools）</b></summary>
**Memory Access**
| Tool | Description |
|---|---|
| `store_memory` | Store memory (automatic vectorization + deduplication + desensitization) |
| `recall_memory` | Semantic search (supports `product_line` three-level cascade) |
| `list_memories` | Paginate and list (multi-dimensional filtering) |
| `update_memory` | Update memory |
| `archive_memory` | Archive |
**Automatic Learning**
| Tool | Description |
|---|---|
| `index_documents` | Batch index directory documents |
| `sync_documents` | Incremental synchronization based on git diff |
| `learn_from_commits` | Extract knowledge from Git history |
| `learn_from_review` | Extract specifications from Code Review |
| `watch_docs` | Real-time monitoring of document changes |
**Topology**
| Tool | Description |
|---|---|
| `scan_topology` | Automatic scanning of warehouses, detecting 15+ language dependencies |
| `import_topology` | Import service architecture from registry |
| `query_topology` | Query service call relationship |
| `get_topology_release_order` | Generate release order |
| `get_topology_change_impact` | Analyze change impact range |
| `resolve_service_path` | Fuzzy match service path |
**Knowledge Accumulation**
| Tool | Description |
|---|---|
| `bootstrap` | One-click cold start |
| `store_session_summary` | Store session decision summary |
| `store_log_insight` | Log troubleshooting conclusion storage |
| `store_troubleshoot` | Troubleshooting process knowledgeization |
| `store_incident` | Online fault structured entry |
| `store_code_review` | Code Review result storage |
**Work Tracking**
| Tool | Description |
|---|---|
| `start_work_context` | Start work context |
| `update_work_context` | Update progress |
| `evaluate_work_context` | Complete evaluation, automatic sedimentation of experience |
**Others**
| Tool | Description |
|---|---|
| `get_developer_profile` | Developer skill image |
| `get_system_rules` | Load team specifications (non-Cursor IDE applicable) |
| `verify_memory` | Mark memory as verified (+15% sorting weight) |
| `export_memories` / `import_memories` | Data import and export |
| `store_structured_memory` | Unified structured storage entry (routing to code_review/session_summary/log_insight, etc.) |
| `extract_session_memories` | Automatically extract valuable memories from session content (architecture decision/Bug mode/experience lesson) |
| `index_api_docs` | Index warehouse API documentation (automatically extract function signature and usage) |
**Git History Knowledge Engine**
| Tool | Description |
|---|---|
| `bootstrap_project_history` | One-click import Git history knowledge (analyze submission/PR/Review) |
| `check_stale_code` | Detect code corruption risk (long-term unchanged module) |
| `check_conflict_risk` | Evaluate concurrent modification conflict risk |
| `get_project_context` | Get project context (contributor/activeness/technical stack) |
| `check_related_activity` | Check up and down stream warehouse recent change impact |
| `extract_coding_standards` | Batch extract coding specification candidates from Git history |
| `review_commit` | Execute automatic Code Review pipeline for single Git commit (context collection → static scanning → LLM review → Dingtalk notification) |
| `install_git_hooks` | Install Memforge post-commit & post-merge hooks for Git warehouse |
**Agent Task Management**
| Tool | Description |
|---|---|
| `get_agent_tasks` | Get task list |
| `create_agent_task` | Create task |
| `update_agent_task` | Update task status |
| `batch_update_tasks` | Batch update tasks |
| `log_task_progress` | Record task progress |
| `import_tasks_from_plan` | Import tasks from plan |
| `manage_agent_tasks` | Task management (multi-operation integration) |
</details>
<details>
<summary><b>Rules Engine（19 tools）</b></summary>
| Tool | Description |
|---|---|
| `propose_rule` | Propose rules (automatic conflict detection) |
| `list_rules` | List rules |
| `get_rule` | Get details (including voting and measurement) |
| `vote_rule` | Weighted voting |
| `update_rule` | Update candidate rules |
| `activate_rule` | Activate candidate rules |
| `delete_rule` | Delete rules |
| `deprecate_rule` | Deprecate rules |
| `enforce_rules` | Execute rule checks on code |
| `discover_rules` | Analyze content to discover rule candidates |
| `measure_rules` | Rule effect measurement |
| `record_rule_event` | Record application/violation events |
| `assess_skill` | Skill assessment |
| `get_growth_path` | Growth path recommendation |
| `record_milestone` | Record growth milestones |
| `get_skill_radar` | Skill radar chart data |
| `get_team_matrix` | Team skill matrix |
| `add_knowledge_relation` | Establish knowledge graph relationship |
| `get_knowledge_graph` | Query knowledge graph |
</details>
<details>
<summary><b>Knowledge Service（10 MCP tools + REST API）</b></summary>
**MCP Tools**
| Tool | Description |
|---|---|
| `search_knowledge` | Hybrid search (BM25 + vector + RRF fusion + confidence score) |
| `store_knowledge` | Store knowledge entries (FAQ/operation guide/fault case, etc. 7 types) |
| `browse_knowledge` | Browse knowledge base directory by file system semantics (VFS URI) |
| `read_knowledge_item` | Read single knowledge entry, return Markdown format (support ID or VFS URI) |
| `write_knowledge_item` | Create or update knowledge entry with file system semantics, automatically generate slug and VFS URI |
| `import_dingtalk_docs` | Import documents from Dingtalk knowledge base (traverse folder tree, convert to knowledge entries) |
| `code_context` | Natural language query, return assembled code knowledge context (project overview + related modules) |
| `knowledge_feedback` | Submit feedback on knowledge entries (helpful/unhelpful), drive confidence sorting optimization |
| `list_knowledge` | Paginate list knowledge entries (support type/classification/product line filtering) |
| `knowledge_stats` | Knowledge base statistical data (entry total, classification distribution, etc.) |
**REST API (WebUI use)**
| Endpoint | Description |
|---|---|
| `POST /api/knowledge/search` | Hybrid search |
| `POST /api/knowledge/store` | Create knowledge |
| `GET /api/knowledge/list` | Paginate list |
| `GET /api/knowledge/:id` | Details |
| `PUT /api/knowledge/:id` | Update knowledge entry |
| `DELETE /api/knowledge/:id` | Delete knowledge entry |
| `POST /api/knowledge/:id/publish` | Publish (draft → published) |
| `POST /api/knowledge/:id/archive` | Archive (published → archived) |
| `POST /api/knowledge/feedback` | Feedback (helpful/unhelpful) |
| `POST /api/knowledge/import-tickets` | Batch import tickets |
| `GET /api/knowledge/browse` | Browse by classification path (with sub-classification and entries) |
| `GET/POST /api/knowledge/categories` | Classification management (hierarchical classification tree) |
| `PUT /api/knowledge/categories/:id` | Update classification |
| `DELETE /api/knowledge/categories/:id` | Delete classification |
| `GET /api/knowledge/stats` | Statistics (by status/type distribution) |
| `POST /api/knowledge/cleanup` | Batch clean up entries by source |
| `POST /api/knowledge/mark-stale` | Mark expired entries (based on file change) |
| `GET /api/knowledge/stale-stats` | Expired entry statistics |
| `POST /api/knowledge/code-context` | Code knowledge context assembly (REST version code_context) |
| `POST /api/memory/recall` | Semantic search memory (REST version recall_memory, with RLS) |
</details>
---
## Project Structure
```
memforge/
├── packages/
│ ├── memory-service/ # Core memory MCP service (48 tools)
│ ├── rules-engine/ # Coding specification engine (19 tools)
│ ├── knowledge-service/ # Knowledge base service (10 MCP tools + hybrid search + review workflow)
│ ├── gateway/ # MCP Gateway (OAuth 2.1 + RBAC + audit)
│ ├── web-ui/ # Vue 3 + Element Plus management panel
│ └── shared/ # Shared types, PG connection pool, cache
├── sql/
│ ├── init.sql # Initialize schema
│ └── migrations/ # Incremental migration script
├── scripts/
│ ├── cursor-hooks/ # Cursor Agent Hooks (automatic recall/specification injection/document synchronization)
│ ├── batch-index-api.ts # Batch API document indexing (with branch guard)
│ ├── batch-deep-index.ts # Deep code knowledge indexing (with branch guard)
│ └── mcp-remote-proxy.mjs # MCP remote proxy client
├── deploy/
│ └── k8s/ # Kubernetes Helm Chart
├── docs/ # Project documentation (create as needed)
├── .github/workflows/ # CI/CD (GitHub Actions)
└── docker-compose.yml
```
---
## Environment Variables
| Variable | Default value | Description |
|---|---|---|
| `TRANSPORT_MODE` | `stdio` | Transport mode (`stdio` / `http`) |
| `DATABASE_URL` | — | PostgreSQL connection string |
| `OPENAI_BASE_URL` | — | Embedding API address |
| `OPENAI_API_KEY` | — | Embedding API key |
| `OPENAI_EMBEDDING_MODEL` | — | Model name (recommended `BAAI/bge-m3`) |
| `MEMFORGE_GATEWAY_URL` | — | Gateway address (Git Hook shared configuration + MCP proxy use) |
| `MEMFORGE_REVIEW_BRANCHES` | `master,main` | Branch whitelist for triggering Code Review (comma separated) |
| `MEMFORGE_AUTO_MODE` | `smart` | Automation mode (`smart` / `full` / `silent`) |
| `MEMFORGE_RULES_SCOPE` | `global` | Rules installation location (`global` / `workspace`) |
| `REDIS_URL` | — | Redis connection string (L2 cache, optional) |
---
## Cursor Rules Automatic Installation
Automatically install two rules to `~/.cursor/rules/` at startup:
- `memforge-auto-recall.mdc` — Automatic recall/storage of memory during AI interaction
- `memforge-human-confirm.mdc` — Human confirmation required before AI executes changes
Set `MEMFORGE_RULES_SCOPE=workspace` to switch to workspace-level installation.
## Git Hook Automatic Installation
Automatically install `post-commit` / `post-merge` hooks when MCP connects to Git repository, triggering knowledge learning and Code Review after code submission.
**Shared configuration mechanism**: Hook script reads Gateway URL from `~/.memforge/config` during runtime (automatically refreshed with each MCP connection), server migration only requires updating `MEMFORGE_GATEWAY_URL` environment variable, and any repository can automatically propagate new address to all repository hooks.
---
## Roadmap
<details>
<summary>View complete milestone history</summary>
- [x] M1: Core memory service (SQLite + local vectorization)
- [x] M2: Coding specification engine (Rules Engine — voting + conflict detection + measurement)
- [x] M3a: PostgreSQL migration (pgvector + FTS + Docker Compose)
- [x] M3b: MCP Gateway (OAuth 2.1 + PKCE + RBAC + audit)
- [x] M3c: Multi-tenancy (RLS + Redis cache + Prometheus observability)
- [x] M4: Web UI (Vue 3 + Element Plus)
- [x] M5: Production readiness (backup recovery + Helm Chart + deployment manual)
- [x] M6: Skill tree and growth system
- [x] M7: Automatic knowledge acquisition (document indexing + commit learning + review extraction)
- [x] M8: Engineering completion (Dockerfile + CI reinforcement + E2E coverage)
- [x] M9: Smart Semi-Auto (Auto-Init Hook)
- [x] M10: Web UI practicalization (topology visualization)
- [x] M11: Cursor Rules automatic installation
- [x] M12: Knowledge closed loop (bootstrap + bidirectional specification synchronization)
- [x] M13: Four-layer visibility (personal → team → product_line → global)
- [x] M14: Work context tracking
- [x] M15: Specification governance enhancement (rule-bridge + store_code_review)
- [x] M16: Topology query MCPization (4 read-only query tools)
- [x] M17: Operation and maintenance tool chain (watchdog + log-rotate + backup)
- [x] M18: Developer portrait
- [x] T1: Team transformation (RBAC + product line ACL + Gateway native MCP)
- [x] M19: Intelligent agent task center (Agent Task + Kanban)
- [x] M20: Cursor Hooks system-level mandatory guarantee (recall/specification injection/document synchronization/GATE 0)
- [x] M21: Git history knowledge engine (6 tools)
</details>
---
## Migration
If you previously used the old version based on SQLite:
```bash
node scripts/migrate-sqlite-to-pg.mjs \
--memory-db ~/.memforge/data/memforge.db \
--rules-db ~/.memforge/data/rules.db
```
---
## Contribution
Welcome PR and Issue! Please read [User Guide](docs/user-guide.md) to understand project architecture.
```bash
# Local development
npm install
docker compose up -d # Start PostgreSQL + Redis
npm run build # Compile all packages
npm run test -w packages/memory-service # Run test
```
---
## License
[MIT](LICENSE) © 2026 Memforge Contributors
---
<div align="center">
[](https://star-history.com/#zql0805/memforge)
</div>
