Skip to content
Back to search

efka

AI-powered knowledge management without vector embeddings. Built upon Claude Agent SDK, File system based, Agent driven. Maybe slower, but results are much more reliable!

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/harryoung--efka/badge.svg)](/listings/harryoung--efka)

HTML

<a href="/listings/harryoung--efka"><img src="/api/listings/harryoung--efka/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.10+ - Node.js 20.19+ (required by Vite 7.x) - Claude Code CLI - Install: `npm install -g @anthropic-ai/claude-code` - Redis 7+ (optional, uses memory storage if not installed) - macOS: `brew install redis && brew services start redis` - Ubuntu: `sudo apt-get install redis-server && sudo systemctl start redis` - Claude API Key - Pandoc (for document conversion) - macOS: `brew install pandoc` - Ubuntu: `apt-get install pandoc`

Installation

# Clone the repository
git clone https://github.com/Harryoung/efka.git
cd efka

# Configure environment
cp .env.example .env
# Edit .env with your Claude API Key and other settings

# Install backend dependencies
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r backend/requirements.txt

# Install frontend dependencies
cd frontend && npm install && cd ..

# Start services
./scripts/start.sh

Access the application: - **Admin UI**: http://localhost:3000 (knowledge base management) - **User UI**: http://localhost:3001 (Q&A interface) - **API**: http://localhost:8000/health

Stop services: `./scripts/stop.sh`

Docker Deployment

cp .env.example .env
# Edit .env with your configuration

docker compose up -d

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 416 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg">
  5. <img src="assets/logo-light.svg" width="120" height="120" alt="EFKA Logo">
  6. </picture>
  7. </p>
  8. <h1 align="center">EFKA 知了 - Embed-Free Knowledge Agent</h1>
  9. <p align="center">
  10. <em>AI-powered knowledge management without vector embeddings. File system based, Agent driven. Maybe slower, but results are much more reliable!</em>
  11. </p>
  12. <p align="center">
  13. <strong>知了</strong> (Zhīliǎo, Chinese for "Cicada") - The name symbolizes clear, resonant communication of knowledge.
  14. </p>
  15. [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  16. [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
  17. [![Claude](https://img.shields.io/badge/Claude-Agent%20SDK-orange.svg)](https://github.com/anthropics/claude-code)
  18. English | [中文](README_CN.md)
  19. > [!IMPORTANT]
  20. > ## News
  21. > A new standalone Skill project has been released based on EFKA's core capabilities:
  22. > **[`local-knowledge-base`](https://github.com/Harryoung/local-knowledge-base)**.
  23. >
  24. > If you are interested in EFKA's knowledge-base workflow, see that project for related code and usage details.
  25. <p align="center">
  26. <img src="assets/demo.gif" alt="EFKA Demo" width="640">
  27. </p>
  28. ## Why EFKA?
  29. Traditional RAG systems rely on vector embeddings and similarity search, which can miss context and produce hallucinations. EFKA takes a different approach:
  30. - **No Embeddings**: Direct file system access, no vector database needed
  31. - **Agent-First**: Let the AI agent intelligently search and combine information
  32. - **Transparent**: You can read the same files the agent reads
  33. - **Reliable**: No semantic drift or embedding quality issues
  34. ## EFKA vs. Traditional Embedding-based RAG
  35. <p align="center">
  36. <img src="assets/EFKA_overview_en.png" alt="EFKA System Overview" width="800">
  37. </p>
  38. EFKA represents a paradigm shift from traditional embedding-based RAG systems. Instead of fragmenting documents into chunks and relying on similarity search, EFKA adopts a human-like, tree-search approach that directly interacts with your knowledge base files.
  39. | Dimension | Traditional RAG | EFKA | Example |
  40. |-----------|-----------------|------|---------|
  41. | **Information Integrity** | Documents split into chunks, disrupting logical flow | Reads complete sections, preserving context | *Querying "employee onboarding process": Traditional RAG retrieves scattered chunks from HR policy, missing the required sequence. EFKA reads the full onboarding guide and provides step-by-step instructions.* |
  42. | **Chunking Strategy** | Quality depends heavily on chunk size/overlap settings | No chunking required | *A 50-page technical manual: Traditional RAG must tune chunk sizes (too small loses context, too large retrieves noise). EFKA navigates via TOC to the relevant section.* |
  43. | **Context Completeness** | No guarantee retrieved chunks contain all needed info | Follows document structure to gather complete context | *"What's the refund policy for enterprise customers?" Traditional RAG may only retrieve general refund rules, missing the enterprise-specific exceptions in a later paragraph. EFKA reads the entire policy section.* |
  44. | **Similarity Threshold** | Hard to tune – too high misses info, too low adds noise | Uses LLM reasoning, no threshold tuning | *Searching for "API rate limits": Traditional RAG may miss "request throttling" (different wording). EFKA understands synonyms and finds all related content.* |
  45. | **Information Aggregation** | Cannot reliably aggregate semantically similar content | Agent intelligently synthesizes across documents | *"Summarize Q1-Q3 weekly reports into a quarterly summary": Traditional RAG retrieves all weekly reports (semantically identical) but cannot distinguish which weeks belong to which month. EFKA reads each report, extracts dates, and organizes by time period.* |
  46. | **Knowledge Base Quality Control** | No ingestion-time quality enforcement; conflicting content may coexist | Strict ingestion standards with conflict detection | *Two policy documents with contradictory vacation rules: Traditional RAG stores both, causing inconsistent answers. EFKA's Admin Agent detects conflicts during ingestion and requires resolution before adding.* |
  47. | **Infrastructure Complexity** | Requires embedding models + vector DB + often rerankers | Only needs LLM API | *Setting up a new knowledge base: Traditional RAG needs Pinecone/Milvus/Weaviate + embedding model deployment. EFKA just needs a folder of files.* |
  48. | **Domain Adaptation** | General embeddings may miss domain-specific semantics | LLM understands domain context directly | *Medical knowledge base: "MI" means "myocardial infarction" not "Michigan". Traditional RAG may confuse these; EFKA understands from context.* |
  49. | **Update Cost** | Adding/modifying docs requires re-embedding entire dataset | Just add/edit files, no re-indexing | *Adding 100 new documents: Traditional RAG must re-embed and update vector indices. EFKA: just copy files to the knowledge base folder.* |
  50. | **Multi-Modal Support** | Requires separate pipelines for images/tables | Native support via LLM vision capabilities | *Document with embedded diagrams: Traditional RAG often ignores images. EFKA can read and interpret diagrams in context.* |
  51. | **Transparency** | Black-box similarity scores | Full visibility into which files are read | *Debugging wrong answers: Traditional RAG shows similarity scores that are hard to interpret. EFKA shows exactly which files and sections were consulted.* |
  52. ## Features
  53. - **Intelligent Q&A**: 6-stage retrieval strategy with expert routing - accurate answers with source attribution
  54. - **Smart Document Ingestion**: Automatic format conversion, semantic conflict detection, intelligent file placement
  55. - **FAQ System**: Automatic learning from interactions, usage tracking, and optimization
  56. - **Multi-Channel Support**: Web UI + Enterprise IM platforms (WeChat Work, Feishu, DingTalk, Slack)
  57. - **Dual-Agent Architecture**: Separate agents optimized for admin tasks and user queries
  58. - **Streaming Responses**: Real-time SSE streaming with Markdown rendering
  59. - **Progressive README Layering**: Auto-generates hierarchical README structure as knowledge base grows, ensuring fast navigation at any scale
  60. ## Limitations and Use Cases
  61. ### Limitations
  62. While EFKA provides more reliable and accurate answers compared to traditional RAG systems, it has some inherent limitations:
  63. 1. **Latency**: Response times are longer than traditional RAG, typically in the 10-30 second range. The system aims for near-real-time performance but cannot match the sub-second response times of embedding-based systems.
  64. 2. **Token Consumption**: The agent-based approach consumes more tokens as it reads entire documents or sections. This requires more powerful models and results in higher API costs compared to simple similarity search.
  65. 3. **Concurrency Architecture**: Because the Claude Agent SDK wraps CLI processes, each conversation requires a separate CLI process. While EFKA implements a client pool for concurrency management, this approach is less elegant than traditional API-based systems. Related issue: [#333](https://github.com/anthropics/claude-agent-sdk-python/issues/333).
  66. ### Suitable Use Cases
  67. EFKA is best suited for scenarios where:
  68. - **Accuracy over Speed**: When answer quality and reliability are more important than response time
  69. - **Low to Moderate Frequency**: For occasional or periodic queries rather than high-volume, real-time interactions
  70. - **Knowledge-Intensive Domains**: Complex domains where context preservation and complete information retrieval are critical
  71. - **Transparency Requirements**: When users need to verify information sources and understand the reasoning process
  72. ### Not Suitable For
  73. - **Real-Time Chat**: Applications requiring sub-second response times
  74. - **High-Frequency Queries**: Scenarios with thousands of queries per hour where cost would be prohibitive
  75. - **Simple FAQ Lookups**: When a traditional vector database would be sufficient and faster
  76. Understanding these trade-offs helps determine when EFKA is the right solution for your knowledge management needs.
  77. ## Agent Workflow
  78. ### Admin Agent Flow
  79. ```mermaid
  80. flowchart TD
  81. subgraph Intent["🎯 Intent Recognition"]
  82. A[User Request] --> B{Intent Type?}
  83. end
  84. subgraph DocIngest["📥 Document Ingestion"]
  85. B -->|Upload/Add/Import| C1[1. Validate Format]
  86. C1 -->|MD/TXT| C3
  87. C1 -->|Excel| C2a[Keep Original + Generate Metadata]
  88. C1 -->|DOC/PDF/PPT| C2b[smart_convert.py]
  89. C2a --> C3[3. Semantic Conflict Detection]
  90. C2b --> C3
  91. C3 -->|Conflict| C3x[Report & Suggest Adjustment]
  92. C3 -->|No Conflict| C4[4. Determine Target Location]
  93. C4 --> C5[5. Write & Update README.md]
  94. C5 -->|Large File| C5a[Generate TOC Overview]
  95. end
  96. subgraph KBMgmt["📚 KB Management"]
  97. B -->|View/List/Stats| D1[Read README/FAQ/Stats]
  98. B -->|Delete| D2[Show Details & Request Confirm]
  99. D2 -->|User Confirms| D3[Delete & Update README]
  100. D2 -->|User Cancels| D4[Abort]
  101. end
  102. subgraph BatchNotify["📢 Batch Notification (Requires IM Integration)"]
  103. B -->|Notify/Send| E1[Read User Mapping]
  104. E1 --> E2[Filter Target Users]
  105. E2 --> E3[Build Message & Preview]
  106. E3 -->|User Confirms| E4[Batch Send via IM]
  107. end
  108. style Intent fill:#e1f5fe
  109. style DocIngest fill:#f3e5f5
  110. style KBMgmt fill:#e8f5e9
  111. style BatchNotify fill:#fff3e0
  112. ```
  113. ### User Agent Flow
  114. ```mermaid
  115. flowchart TD
  116. subgraph Query["🔍 6-Stage Knowledge Retrieval"]
  117. A[User Query] --> B[1. FAQ Quick Match]
  118. B -->|Found| B1[Return FAQ Answer]
  119. B -->|Not Found| C[2. Navigate via README.md]
  120. C --> D{Target Files?}
  121. D -->|Identified| E[3. Smart File Read]
  122. D -->|Unclear| F[4. Keyword Search]
  123. E -->|Small File| E1[Read Full Content]
  124. E -->|Large File| E2[Read TOC → Target Section]
  125. E1 & E2 --> G{Answer Found?}
  126. F -->|Max 3 Attempts| G
  127. G -->|Yes| H[5. Generate Answer + Source]
  128. G -->|No| I[6. Expert Routing]
  129. end
  130. subgraph Expert["👨‍💼 Expert Routing (Requires IM Integration)"]
  131. I --> I1[Identify Domain]
  132. I1 --> I2[Query domain_experts.xlsx]
  133. I2 --> I3[Notify Expert via IM]
  134. I3 --> I4[Inform User to Wait]
  135. end
  136. subgraph Feedback["💬 Satisfaction Feedback"]
  137. H --> J[User Feedback]
  138. J -->|Satisfied + From FAQ| K1[Update FAQ Usage Count]
  139. J -->|Satisfied + From KB| K2[Add to FAQ]
  140. J -->|Unsatisfied + Has Reason| K3[Update FAQ Content]
  141. J -->|Unsatisfied + No Reason| K4[Remove FAQ + Log BADCASE]
  142. end
  143. style Query fill:#e3f2fd
  144. style Expert fill:#fce4ec
  145. style Feedback fill:#f1f8e9
  146. ```
  147. ## Architecture
  148. ```
  149. ┌──────────────────────────────────────────────────────┐
  150. │ Frontend Layer │
  151. │ ┌─────────────┐ ┌──────────────────────────────┐ │
  152. │ │ Web UI │ │ IM Platforms │ │
  153. │ │ (3000) │ │ WeWork / Feishu / DingTalk │ │
  154. │ └──────┬──────┘ └──────────────┬───────────────┘ │
  155. │ └────────────┬───────────┘ │
  156. ├──────────────────────┼───────────────────────────────┤
  157. │ Backend (FastAPI) │ │
  158. │ ┌─────────────┐ ┌──┴──────────┐ │
  159. │ │ Admin Agent │ │ User │ │
  160. │ │ - Doc Mgmt │ │ Agent │ │
  161. │ │ - KB Admin │ │ - Q&A │ │
  162. │ │ - Notify │ │ - Routing │ │
  163. │ └─────────────┘ └─────────────┘ │
  164. ├──────────────────────────────────────────────────────┤
  165. │ Infrastructure: Redis | Knowledge Base | Channels │
  166. └──────────────────────────────────────────────────────┘
  167. ```
  168. ## Quick Start
  169. ### Prerequisites
  170. - Python 3.10+
  171. - Node.js 20.19+ (required by Vite 7.x)
  172. - Claude Code CLI
  173. - Install: `npm install -g @anthropic-ai/claude-code`
  174. - Redis 7+ (optional, uses memory storage if not installed)
  175. - macOS: `brew install redis && brew services start redis`
  176. - Ubuntu: `sudo apt-get install redis-server && sudo systemctl start redis`
  177. - Claude API Key
  178. - Pandoc (for document conversion)
  179. - macOS: `brew install pandoc`
  180. - Ubuntu: `apt-get install pandoc`
  181. ### Installation
  182. ```bash
  183. # Clone the repository
  184. git clone https://github.com/Harryoung/efka.git
  185. cd efka
  186. # Configure environment
  187. cp .env.example .env
  188. # Edit .env with your Claude API Key and other settings
  189. # Install backend dependencies
  190. python -m venv venv
  191. source venv/bin/activate # Windows: venv\Scripts\activate
  192. pip install -r backend/requirements.txt
  193. # Install frontend dependencies
  194. cd frontend && npm install && cd ..
  195. # Start services
  196. ./scripts/start.sh
  197. ```
  198. Access the application:
  199. - **Admin UI**: http://localhost:3000 (knowledge base management)
  200. - **User UI**: http://localhost:3001 (Q&A interface)
  201. - **API**: http://localhost:8000/health
  202. Stop services: `./scripts/stop.sh`
  203. ### Docker Deployment
  204. ```bash
  205. cp .env.example .env
  206. # Edit .env with your configuration
  207. docker compose up -d
  208. ```
  209. ## Configuration
  210. Key environment variables (see `.env.example` for full list):
  211. | Variable | Description | Required |
  212. |----------|-------------|----------|
  213. | `CLAUDE_API_KEY` or `ANTHROPIC_AUTH_TOKEN` | Claude API authentication (choose one) | Yes |
  214. | `ANTHROPIC_BASE_URL` | API Base URL (required when using AUTH_TOKEN) | Conditional |
  215. | `KB_ROOT_PATH` | Knowledge base directory | No (default: ./knowledge_base) |
  216. | `REDIS_HOST` | Redis host | No (default: localhost) |
  217. | `WEWORK_CORP_ID` | WeChat Work Corp ID | For WeWork integration |
  218. > **💡 Alternative Models**: If you don't have an Anthropic API key, you can use compatible models such as DeepSeek V3.2, GLM 4.6, Minimax M2, Kimi K2, Doubao-Seed-Code, etc. Simply configure `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` in your `.env` file. Please search online for specific setup tutorials for your chosen provider.
  219. >
  220. > **⚠️ Thinking Mode**: Extended thinking is disabled by default because third-party API providers (DeepSeek, GLM, Minimax, etc.) may not yet support the Claude Agent SDK's thinking mode response format. If you're using the official Anthropic API and want to enable thinking, modify `max_thinking_tokens` in `backend/services/kb_service_factory.py`.
  221. ### Run Mode Configuration (v3.0)
  222. EFKA v3.0 introduces explicit run mode configuration. By default, it runs in **standalone** mode (Web-only). To enable IM integration, configure `RUN_MODE`:
  223. ```bash
  224. # Standalone mode (default) - Pure Web, no IM integration
  225. ./scripts/start.sh
  226. # WeChat Work mode
  227. ./scripts/start.sh --mode wework
  228. # Or via environment variable
  229. RUN_MODE=wework ./scripts/start.sh
  230. ```
  231. **Available modes**: `standalone`, `wework`, `feishu`, `dingtalk`, `slack`
  232. **Note**: Only one IM channel can be active at a time (single-channel mutual exclusivity).
  233. ### IM Platform Integration
  234. Configure the corresponding environment variables for your chosen IM platform:
  235. ```bash
  236. # Run mode
  237. RUN_MODE=wework
  238. # WeChat Work configuration
  239. WEWORK_CORP_ID=your_corp_id
  240. WEWORK_CORP_SECRET=your_secret
  241. WEWORK_AGENT_ID=your_agent_id
  242. ```
  243. See [Channel Development Guide](docs/CHANNELS.md) for adding new platforms.
  244. ## Project Structure
  245. ```
  246. efka/
  247. ├── skills/ # Agent skills (SDK native mechanism)
  248. ├── backend/
  249. │ ├── agents/ # Agent definitions (Admin + User)
  250. │ ├── api/ # FastAPI routes
  251. │ ├── channels/ # IM platform adapters
  252. │ ├── services/ # Business logic
  253. │ ├── tools/ # Custom tools (image_read, etc.)
  254. │ └── utils/ # Utilities
  255. ├── frontend/ # React Web UI
  256. ├── knowledge_base/ # Document storage
  257. │ └── .claude/skills/ # Agent skills (auto-copied on startup)
  258. ├── scripts/ # Deployment scripts
  259. ├── docs/ # Documentation
  260. └── wework-mcp/ # WeChat Work MCP server (submodule)
  261. ```
  262. ### Skills Directory
  263. The `skills/` directory contains Agent skills using Claude Agent SDK's native mechanism:
  264. - `batch-notification/` - Batch user notification workflow
  265. - `document-conversion/` - Document format converter (DOC/PDF/PPT → Markdown)
  266. - `excel-parser/` - Smart Excel/CSV parsing with automatic complexity-based strategy selection
  267. - `expert-routing/` - Domain expert routing
  268. - `large-file-toc/` - Large file table of contents generation
  269. - `satisfaction-feedback/` - User satisfaction feedback handling
  270. **Important**: These files are automatically copied from `skills/` to `knowledge_base/.claude/skills/` on startup to ensure agents only access files within the knowledge base directory boundary.
  271. ## Documentation
  272. - [Deployment Guide](docs/DEPLOYMENT.md) - Production deployment instructions
  273. - [Channel Development Guide](docs/CHANNELS.md) - Adding new IM platform support
  274. ## Roadmap
  275. ### IM Platform Integrations
  276. Currently only **WeChat Work** is fully implemented. The following platforms are planned:
  277. | Platform | Status | Notes |
  278. |----------|--------|-------|
  279. | WeChat Work | ✅ Implemented | Full feature support |
  280. | Feishu (Lark) | 🔜 Planned | Event subscription + message API |
  281. | DingTalk | 🔜 Planned | Robot callback + message push |
  282. | Slack | 🔜 Planned | Slack App with Events API |
  283. Each platform will implement `BaseChannelAdapter` interface. See [Channel Development Guide](docs/CHANNELS.md) for implementation details.
  284. ### Enterprise Access Control System
  285. **Goal**: Fine-grained file-level permission control for multi-tenant enterprise deployments.
  286. **Core Design**: Leverage Claude Agent SDK's `PreToolUse` hook to intercept `Read` / `Glob` / `Grep` tool calls and enforce permission checks before file access.
  287. ```
  288. ┌─────────────────────────────────────────────────────────┐
  289. │ PreToolUse Hook (Permission Gate) │
  290. │ ┌─────────────────────────────────────────────────┐ │
  291. │ │ 1. Extract file paths from tool input │ │
  292. │ │ 2. Query permission service (user → ACL) │ │
  293. │ │ 3. ALLOW / DENY / FILTER (partial access) │ │
  294. │ └─────────────────────────────────────────────────┘ │
  295. ├─────────────────────────────────────────────────────────┤
  296. │ Permission Service │
  297. │ ├─ User identity (from session / IM context) │
  298. │ ├─ Role → Permission mapping (RBAC) │
  299. │ ├─ File / Directory ACL rules │
  300. │ └─ Audit logging │
  301. └─────────────────────────────────────────────────────────┘
  302. ```
  303. **Key Features**:
  304. - **Path-based ACL**: Define allow/deny rules at directory or file level
  305. - **Role-Based Access Control (RBAC)**: Map users to roles, roles to permissions
  306. - **IM-aware Identity**: Auto-resolve user identity from WeChat Work / Feishu / DingTalk context
  307. - **Audit Trail**: Log all file access attempts for compliance
  308. ## Tech Stack
  309. - **Backend**: Python / FastAPI / Claude Agent SDK / Redis
  310. - **Frontend**: React 18 / Vite / Tailwind CSS
  311. - **AI**: Claude (via Agent SDK)
  312. - **Document Processing**: PyMuPDF / pypandoc / PaddleOCR
  313. ## Contributing
  314. Contributions are welcome! Please feel free to submit issues and pull requests.
  315. ## License
  316. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  317. ## Acknowledgments
  318. Built with [Claude Agent SDK](https://github.com/anthropics/claude-code) by Anthropic.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.