back
loading skill details...
Memora — Personal AI Knowledge Base with interactive knowledge graph visualization. A self-hosted system for managing, retrieving, and querying your personal...
---
name: memora-knowledge-graph
description: >
Memora — Personal AI Knowledge Base with interactive knowledge graph visualization.
A self-hosted system for managing, retrieving, and querying your personal knowledge assets
using vector search, hybrid retrieval, and LLM-driven intelligent Q&A.
Features document upload/processing, semantic search, AI chat sessions, web scraping,
and Obsidian-style knowledge graph visualization with force-directed layout.
Use when: user wants to build a personal knowledge base, manage documents, perform semantic search,
have AI-powered conversations about their knowledge, visualize document/entity relationships,
or integrate knowledge management into their OpenClaw workflow.
metadata:
version: 2.1.0
author: zzlzzlzzl15
license: MIT
openclaw:
requires:
env:
- KB_API_BASE
---
# Memora - Personal AI Knowledge Base
**Memora** is a self-hosted personal AI knowledge base system that provides an integrated experience from knowledge capture to intelligent Q&A. Built on vector retrieval, hybrid search, and LLM-driven intelligent organization, it helps you efficiently manage, retrieve, and utilize your personal knowledge assets.
## Version History
### v2.1.0 (Current)
- 🕸️ **Knowledge Graph Full Build**: Entity extraction now processes all text chunks (removed 10-chunk limit)
- 🗑️ **Document Deletion Consistency**: Soft delete and purge now sync cleanup Neo4j graph data
- 🔧 **Entity ID Fix**: Resolved missing entity_id issue causing node loss in graph queries
- ⚡ **Performance Optimization**: Removed MySQL consistency check during queries, moved to deletion time
- 📦 **Directory Restructure**: Renamed skill directory to memora-knowledge-base for ClawHub compatibility
### v2.0.4
- 📝 **Complete Product Documentation**: Comprehensive README with full product overview
- 🎨 **Knowledge Graph v2.0**: Preview + Fullscreen Modal architecture
- 🖱️ **Enhanced Interactions**: Zoom, pan, drag, hover details
- 🎯 **Centered Layout**: Force-directed algorithm with origin-centered positioning
- 🔄 **Smart Caching**: Preview data cached, modal uses larger dataset
- **Dual Views**: Document graph + Entity graph
### v2.0.0
- Initial release with knowledge graph visualization
- Force-directed layout with interactive controls
- Obsidian-inspired visual design
## Core Features
### 🔐 Privacy & Local Deployment
- **Fully Private**: Data stored locally, no third-party uploads
- **Offline Ready**: Works without internet connection
- **Single User Mode**: No authentication required, ready to use out of the box
### Intelligent Semantic Retrieval
- **Hybrid Search**: Dense vectors + BM42 sparse vectors dual-engine retrieval
- **Relevance Reranking**: Optional Rerank model for secondary sorting
- **Fallback Mechanism**: Automatic fallback to backup strategies
- **Semantic Understanding**: Vector similarity-based, not keyword matching
### 📄 Multi-Format Document Processing
- **Supported Formats**: PDF, Word (.docx/.doc), Plain Text (.txt), Markdown (.md)
- **Smart Chunking**: LangChain recursive character splitter with Chinese/English support
- **Vector Storage**: Dense + sparse vectors stored in Qdrant
- **Metadata Management**: Tags and custom metadata for organization
### AI-Powered Q&A
- **Two Interaction Modes**:
- **Knowledge Query**: Precise Q&A based on retrieved results
- **Knowledge Organization**: LLM automatically organizes and summarizes knowledge
- **Streaming Output**: Real-time content generation
- **Session Management**: Multi-turn conversations with history
- **Source Attribution**: Answers include source document links
### 🕸️ Knowledge Graph Visualization
- **Force-Directed Layout**: Automatic node positioning forming natural network structure
- **Dual View Display**: Document relationship graph + Entity relationship graph
- **Interactive Operations**:
- Mouse wheel zoom (centered on cursor)
- Drag blank area to pan canvas
- Drag nodes to reposition
- Hover to show details
- **Obsidian Style Design**: Black nodes, white background, subtle connections
### 🌐 Web Scraping & Integration
- **Built-in Crawler**: httpx + BeautifulSoup, no external dependencies
- **OpenClaw Integration**: Available as AI Agent Skill with zero-dependency client
- **RESTful API**: Easy integration with other systems
## Quick Start
### Installation via clawhub
```bash
openclaw skills install memora-knowledge-graph@2.0.4
```
### Manual Installation
```bash
# Clone repository
git clone https://github.com/zzlzzlzzl15/Memora.git
cd Memora/personal_knowledge_base
# Run installation script
./install.sh
```
### Docker Compose Deployment (Recommended)
```bash
# Clone repository
git clone https://github.com/zzlzzlzzl15/Memora.git
cd Memora/personal_knowledge_base
# Configure environment variables
cp .env.example .env
# Edit .env with your API keys
# Start services
docker-compose up -d
# Access application
# Open http://localhost:8080 in browser
```
## Configuration
Set the `KB_API_BASE` environment variable to point to your Memora backend:
```bash
export KB_API_BASE=http://127.0.0.1:8080
```
Or create a `.env` file:
```
KB_API_BASE=http://127.0.0.1:8080
```
### Required Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `KB_API_BASE` | Memora backend URL | `http://127.0.0.1:8080` |
| `DEEPSEEK_API_KEY` | DeepSeek API Key (for LLM) | `sk-xxx` |
| `DASHSCOPE_API_KEY` | DashScope API Key (for embeddings) | `sk-xxx` |
### Optional Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `USE_RERANK` | Enable reranking | `false` |
| `RERANK_API_KEY` | Qwen3-Rerank API Key | - |
| `RETRIEVAL_TOP_K` | Initial retrieval candidates | `20` |
| `QDRANT_DENSE_DEFAULT_THRESHOLD` | Dense vector similarity threshold | `0.7` |
## Usage Examples
### Upload Documents
1. Click **"Upload Document"** button in left sidebar
2. Select file (PDF, DOCX, TXT, MD supported)
3. Fill in title and tags (optional)
4. Click **"Upload"** - system automatically parses, chunks, and vectorizes
### Ask Questions
1. Enter question in right-side chat interface
2. Choose interaction mode:
- **Knowledge Query**: Get precise answers based on retrieval
- **Knowledge Organization**: Let AI organize and summarize related knowledge
3. View answer with cited source documents
### Browse Knowledge Graph
1. Click **"Knowledge Graph"** button in top navigation
2. View two preview cards:
- **Document Relationship Graph**: Shows connections between documents
- **Entity Relationship Graph**: Shows extracted entities and relationships
3. Click any card to enter fullscreen modal for interactive exploration:
- Scroll to zoom
- Drag to pan
- Drag nodes to reposition
- Hover for details
### Manage Documents
- **View List**: See all documents in left sidebar
- **Search**: Use quick search function
- **Recycle Bin**: View and manage deleted documents (recoverable within 30 days)
- **Permanent Delete**: Permanently remove documents and vector data
## Technical Architecture
```
┌─────────────────────────────────────────┐
│ Web Browser │
│ (Frontend UI - HTML/CSS/JS) │
└──────────────┬──────────────────────────┘
│ HTTP / WebSocket
┌──────────────▼──────────────────────────┐
│ Memora Backend │
│ (FastAPI / Python) │
──────────┬──────────────┬───────────────┤
│ Document │ Retrieval │ AI Services │
│Processing│ Engine │ │
├──────────┼──────────────┼───────────────┤
│• PDF │• Dense Vector│• Embedding │
│ Parser │ Search │ (DashScope/ │
│• DOCX │• Sparse Vector│ Local ST) │
│ Parse │ (BM42) │• LLM Chat │
│• Text │• Hybrid Search│ (DeepSeek/ │
│ Split │• Fallback │ OpenAI Comp)│
│• Metadata│ Logic │• Rerank │
│• Upload │ │ (Qwen3) │
│ API │ │• Stream │
│ │ │ Response │
└────┬─────┴──────┬───────┴───────┬───────┘
│ │ │
┌────▼────┐ ┌────▼──────┐ ┌──────▼──────┐
│ MySQL │ │ Qdrant │ │ External │
│(Metadata)│ │(Vector DB)│ │ APIs │
│ │ │ │ │ │
│• Docs │ │• Dense │ │• DashScope │
│• Users │ │ Vectors │ │• DeepSeek │
│• Sessions│ │• Sparse │ │• OpenAI │
│• History │ │ (BM42) │ │ Compatible │
└─────────┘ └───────────┘ └─────────────┘
```
### Tech Stack
| Component | Technology | Description |
|-----------|------------|-------------|
| **Backend Framework** | FastAPI (Python 3.11+) | High-performance async web framework |
| **Vector Database** | Qdrant | Hybrid retrieval with dense + sparse vectors |
| **Relational Database** | MySQL 8.0 | Document metadata, users, sessions |
| **Embedding Model** | DashScope text-embedding-v4 / Sentence-Transformers | Cloud API or local models |
| **LLM Service** | DeepSeek / OpenAI Compatible | Streaming output, multi-turn chat |
| **Rerank Model** | Qwen3-Rerank (optional) | Improves retrieval relevance |
| **Document Parsing** | PyPDF2, docx2txt, LangChain | Multi-format processing |
| **Web Scraping** | httpx + BeautifulSoup | Built-in crawler, no dependencies |
| **Containerization** | Docker + Docker Compose | One-click deployment |
## Troubleshooting
### Issue: Preview cards not showing
**Solution**: Check browser console for errors. Ensure `initKnowledgeGraph()` is called after DOM ready.
### Issue: Nodes not centered
**Solution**: Hard refresh page (Cmd+Shift+R). Clear browser cache if needed.
### Issue: Cannot drag/zoom in modal
**Solution**: Verify `setInteractive(true)` is called for fullscreen visualizer. Check console logs.
### Issue: Service won't start
**Solution**:
```bash
# Check logs
docker-compose logs -f app
# Clean and restart
docker-compose down -v
docker-compose up -d
```
### Issue: Document upload fails
**Solution**:
- Check file format (PDF, DOCX, TXT, MD only)
- Check file size (default limit: 10MB)
- Review application logs: `docker-compose logs -f app`
### Issue: No retrieval results
**Solution**:
- Confirm documents are uploaded and vectorized
- Try different query terms
- Lower `QDRANT_DENSE_DEFAULT_THRESHOLD` value
### Issue: LLM call fails
**Solution**:
```bash
# Check API key configuration
cat .env | grep API_KEY
# Test API connectivity
curl -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
https://api.deepseek.com/v1/chat/completions \
-d '{"model":"deepseek-chat","messages":[{"role":"user","content":"test"}]}'
```
## Performance Tips
1. **Limit Node Count**: Use smaller limits for previews (50-80 nodes)
2. **Cache Data**: Reuse fetched data instead of reloading
3. **Debounce Resize**: Add debounce to window resize handler
4. **Reduce Iterations**: Lower `iterations` in `initForceLayout()` for faster load (default: 150)
5. **Optimize Rendering**: Skip rendering during rapid mouse movements
## Browser Compatibility
- ✅ Chrome 90+
- ✅ Firefox 88+
- ✅ Safari 14+
- ✅ Edge 90+
Requires:
- Canvas 2D API
- CSS backdrop-filter
- ES6+ JavaScript features
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Commit your changes (`git commit -m 'Add amazing feature'`)
5. Push to the branch (`git push origin feature/amazing-feature`)
6. Submit a pull request
## Support
For issues and questions:
- GitHub Issues: https://github.com/zzlzzlzzl15/Memora/issues
- Email: support@memora.dev
- Documentation: https://github.com/zzlzzlzzl15/Memora/blob/main/personal_knowledge_base/README.md
## Acknowledgments
- Inspired by [Obsidian](https://obsidian.md/) graph view
- Built for [Memora](https://github.com/zzlzzlzzl15/Memora) personal knowledge base
- Uses force-directed layout algorithm similar to D3.js force simulation
- References [RAG-Anything](https://github.com/RAG-Anything/RAG-Anything) for multimodal RAG architecture
---
**Made with ❤️ by zzlzzlzzl15**
*Memora - Your Personal AI Knowledge Base*
don't have the plugin yet? install it then click "run inline in claude" again.