chat-history-lancedb

star 2

LanceDB-based chat history system with message storage, semantic search, and RAG context retrieval.

hiyenwong By hiyenwong schedule Updated 6/3/2026
play_arrow Run Skill in Manus View GitHub

name: chat-history-lancedb description: "LanceDB-based chat history system with message storage, semantic search, and RAG context retrieval."

Chat History LanceDB

Description

基于 LanceDB 的聊天历史数据库系统，提供完整的消息存储、会话管理、向量语义搜索和 RAG 上下文检索功能。支持智谱AI/火山引擎嵌入向量，本地嵌入式存储，零外部服务依赖。

Activation Keywords

  • chat history
  • 聊天历史
  • chat history db
  • lancedb
  • 会话管理
  • session management
  • 语义搜索
  • semantic search
  • RAG
  • 上下文检索
  • 保存对话
  • save conversation
  • 搜索历史
  • search history
  • 导出对话
  • export conversation

Tools Used

  • exec: 运行 CLI 命令进行数据库操作
  • read: 读取导出的对话历史和配置文件
  • write: 保存配置和导出的对话
  • glob: 查找导入文件

Installation

Prerequisites

# Node.js 20.0+
node --version

# Install dependencies
cd collection/skills/chat-history-lancedb
npm install

# Build TypeScript
npm run build

Configure Environment

Copy .env.example to .env and configure:

cp .env.example .env
# Edit .env with your API keys

Required for vector search:

  • ZHIPU_API_KEY: 智谱AI API Key (for embeddings-2)

Optional:

  • CHAT_HISTORY_DB_PATH: 数据库存储路径 (默认: ~/.chat-history-lancedb)
  • CHAT_HISTORY_EMBEDDING_PROVIDER: zhipu 或 volcengine

Verify Installation

# Show help
node dist/index.js --help

# Create a test session
node dist/index.js session create "Test Session"

Usage Patterns

Save a Message

chat-history save --session <session-id> --role user --content "Hello, how are you?"

Search Chat History

# Semantic search (default)
chat-history search "how to use Python"

# Keyword search
chat-history search "how to use Python" --keyword

# Filter by session
chat-history search "how to use Python" --session <session-id>

List Sessions and Messages

# List sessions
chat-history list sessions

# List messages in a session
chat-history list messages --session <session-id>

Session Management

# Create a new session
chat-history session create "My Project"

# Rename a session
chat-history session rename <session-id> "New Title"

Export and Import

# Export session to JSON
chat-history export <session-id> --format json > session.json

# Export session to Markdown
chat-history export <session-id> --format markdown > session.md

RAG Context Retrieval

# Get RAG context for a query
chat-history rag "how do I fix this bug?" --format text

Statistics

# Overall stats
chat-history stats

# Session-specific stats
chat-history stats --session <session-id>

Instructions for Agents

When user requests chat history operations:

Step 1: Parse Request

Identify the operation type:

  • Save/Store: User wants to save messages/conversations
  • Search: User wants to find past messages
  • Retrieve/RAG: User wants context for LLM
  • Manage: Create/list/rename/delete sessions
  • Export/Import: Transfer chat history

Step 2: Check Configuration

Verify setup before proceeding:

# Check if skill directory exists
cd collection/skills/chat-history-lancedb

# Check if node_modules exists
ls -la node_modules

# If not installed:
npm install && npm run build

Step 3: Execute Operation

Based on the request type:

Save Messages

  1. Create a session if needed:

    node dist/index.js session create "Session Title"

  2. Save each message:

    node dist/index.js save \
  --session <session-id> \
  --role user|assistant|system \
  --content "Message content"

Search History

  1. Choose search mode based on query:

    • Semantic: For conceptual queries ("how do I...", "what is...")
    • Keyword: For exact terms (error messages, function names)
    • Hybrid: Best of both (default)

  2. Execute search:

    node dist/index.js search "your query" [--semantic|--keyword]

RAG Context Retrieval

  1. For LLM context requests:

    node dist/index.js rag "user's question" --format text

  2. Include the output in your LLM prompt as context.

Session Management

# List sessions
node dist/index.js list sessions

# View session messages
node dist/index.js list messages --session <id>

# Export for backup
node dist/index.js export <id> --format json > backup.json

Step 4: Format Output

Present results in user-friendly format:

  • Search results: Show score, role, and content snippet
  • Session lists: Show title, last updated, message count
  • RAG context: Present in clear, structured format for LLM
  • Exports: Offer JSON (for machines) and Markdown (for humans)

Step 5: Handle Errors

Common issues and fixes:

  • Embedding provider error: Check API key in .env
  • Database not found: Initialize by creating a session first
  • Permission denied: Check db_path permissions
  • Node not found: Ensure node_modules installed and built

Context Files

The skill uses these context files when available:

.env

# Database path
CHAT_HISTORY_DB_PATH=~/.chat-history-lancedb

# Embedding provider
CHAT_HISTORY_EMBEDDING_PROVIDER=zhipu

# Zhipu AI
ZHIPU_API_KEY=your_api_key_here
ZHIPU_EMBEDDING_MODEL=embeddings-2

# Search defaults
CHAT_HISTORY_SEARCH_LIMIT=10
CHAT_HISTORY_SEARCH_MIN_SCORE=0.5

CHAT_HISTORY_PREFERENCES.md (Optional)

# Chat History Preferences

## Default Session
# Auto-save to this session
default_session: <session-id>

## Auto-Save
auto_save: true
auto_save_interval: 5m

## Search Preferences
default_search_mode: hybrid
default_limit: 15

Error Handling

Embedding Provider Errors

If you see "Embedding provider required" or API errors:
  1. Check that .env file exists in the skill directory
  2. Verify ZHIPU_API_KEY is set correctly
  3. Try keyword search as fallback: add --keyword flag
  4. Fallback to basic CRUD without vector search

Database Initialization Errors

If you see "Database not initialized":
  1. Create a session first to initialize:
     node dist/index.js session create "First Session"
  2. Verify db_path is writable
  3. Check that node_modules are installed: npm install

Module Not Found Errors

If you see "Cannot find module" errors:
  1. cd to collection/skills/chat-history-lancedb
  2. Run: npm install
  3. Run: npm run build
  4. Retry the command

Configuration

CLI Options

Global Options:

  • --db-path <path>: Override database path
  • --env-file <path>: Path to .env file

Search Options:

  • --semantic: Force semantic search
  • --keyword: Force keyword search
  • --session <id>: Filter by session
  • --limit <n>: Max results (default: 10)
  • --min-score <0-1>: Minimum relevance score

Export Options:

  • --format json|markdown: Output format
  • --output <path>: Save to file

Advanced Usage

Batch Import Conversations

# Import from JSON file
node dist/index.js import conversations.json

# The JSON format should be:
# {
#   "session": { "title": "Imported Session", ... },
#   "messages": [
#     { "role": "user", "content": "...", ... },
#     ...
#   ]
# }

Semantic Search with Filtering

# Search within a specific session
chat-history search "how to debug" --session <id> --limit 20

# Filter by minimum score
chat-history search "how to debug" --min-score 0.7

RAG Integration Pattern

When using with an LLM:

// 1. Get RAG context
const context = await exec(`chat-history rag "${userQuery}" --format text`);

// 2. Build prompt
const prompt = `
Context from past conversations:
${context}

User question: ${userQuery}

Please answer based on the context above.
`;

// 3. Send to LLM

Limitations

  • No real-time sync: Local file-based storage only
  • Keyword search limitations: Simple substring matching (not full FTS5)
  • Embedding API required: Vector search needs Zhipu/Volcengine API key
  • No built-in UI: CLI-only interface
  • Single-user design: Optimized for personal use, not multi-tenant

Best Practices

  1. Use meaningful session titles: Helps with organization and search
  2. Auto-generate embeddings: Default behavior, better search results
  3. Regular exports: Backup important conversations
  4. Archive old sessions: Keep list clean, use tags
  5. Combine search modes: Use hybrid search for best results
  6. Monitor API usage: Embedding API calls have costs

Examples

Example 1: Save a Conversation

User: "Save this conversation:
User: How do I use Python for data analysis?
Assistant: You can use pandas and numpy..."

Agent Process:
1. Create a session
2. Save user message
3. Save assistant message
4. Output session ID for future reference

Executes:
cd collection/skills/chat-history-lancedb
npm run build  # if needed

SESSION_ID=$(node dist/index.js session create "Python Data Analysis")
node dist/index.js save --session $SESSION_ID --role user --content "How do I use Python for data analysis?"
node dist/index.js save --session $SESSION_ID --role assistant --content "You can use pandas and numpy..."

Agent: "Conversation saved! Session ID: $SESSION_ID"

Example 2: Semantic Search

User: "Find past conversations about machine learning"

Agent Process:
1. Identify search mode: semantic (conceptual query)
2. Execute search
3. Present results with relevance scores

Executes:
node dist/index.js search "machine learning" --semantic

Agent:
"Found 5 relevant conversations:

[85%] User: How do I train a neural network...
[78%] Assistant: For classification tasks, you can use...
[72%] User: What's the difference between supervised...
..."

Example 3: RAG Context Retrieval

User: "Help me fix that bug we discussed yesterday about database connections"

Agent Process:
1. Retrieve relevant context
2. Build prompt with context
3. Answer using the retrieved information

Executes:
node dist/index.js rag "database connection bug fix" --format text

Agent includes context in its response...

Example 4: Export and Backup

User: "Export my 'Project Alpha' session as Markdown"

Agent Process:
1. Find session ID for "Project Alpha"
2. Export to Markdown
3. Save to file or display

Executes:
# First list sessions to find ID
node dist/index.js list sessions

# Then export
node dist/index.js export <session-id> --format markdown > project-alpha.md

Agent: "Exported to project-alpha.md"

Troubleshooting

Issue: npm install fails

# Try clearing cache
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Issue: Build fails with TypeScript errors

# Make sure you're using correct Node version
node --version  # Should be >= 20

# Reinstall dependencies
rm -rf node_modules
npm install
npm run build

Issue: Can't connect to Zhipu API

# Verify API key is correct
echo $ZHIPU_API_KEY

# Test with curl
curl -X POST "https://open.bigmodel.cn/api/paas/v4/embeddings" \
  -H "Authorization: Bearer $ZHIPU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "embeddings-2", "input": "test"}'

Issue: Database is locked or corrupted

# Backup first
cp -r ~/.chat-history-lancedb ~/.chat-history-lancedb.backup

# Try creating a fresh database
# (export what you can first)
rm -rf ~/.chat-history-lancedb
# Re-initialize by creating a session

Resources

Related Skills

  • skill-rag-indexer: For indexing and searching skills (uses similar architecture)
  • stock-analysis: For Python-based skill pattern reference
  • research-agent: Can use chat history for context-aware research
Install via CLI
npx skills add https://github.com/hiyenwong/ai_collection --skill chat-history-lancedb
Repository Details
star Stars 2
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
hiyenwong
hiyenwong Explore all skills →