knowledge_base_tool

KO | EN

gitlite — search

#ai #typescript #go #docker #macos #java #windows #awesome #cli #kubernetes #vue #pytorch #security #openai

knowledge_base_tool

(★ 9)

All in one tool, for everyday daily steps

knowledge_base_tool Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 📚 Knowledge Base Tool

A local-first personal knowledge base. Everything is a plain **Markdown file**
with YAML frontmatter — readable, greppable, and yours forever. SQLite is used
only for rebuildable indexes.

**FastAPI** + Jinja2 · **SQLite FTS5** search · **Typer** CLI · **pystray** tray
launcher · **PyInstaller** standalone builds.

---

## Quick start

**Docker** (recommended) — see [dockerise/README.md](./dockerise/README.md):

```bash
docker compose -f dockerise/docker-compose.yml up --build -d
```

**Local** — requires **Python 3.10+**:

```bash
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python cli.py serve                # → http://127.0.0.1:5050
```

Add a tray icon with `python launcher.py` (needs a desktop session).

> Port **5050**, not 5000 — macOS uses 5000 for the AirPlay Receiver and returns `403`.

---

## Features

Each one can be toggled in **Settings → Features**.

| | Feature | What it's for |
|---|---|---|
| 📝 | **Posts** | Core notes & articles — tags, categories, full-text search |
| 📚 | **Series** | Chain posts into ordered multi-part topics |
| 📖 | **Books** | Chapter collections + a 3D page-flip reader for PDF/EPUB/MOBI/CBZ/FB2/XPS |
| 🧩 | **Diagrams** | Mermaid & PlantUML with live preview → export markdown, SVG, or PNG |
| 🗒️ | **Notes** | Sticky-note grid with pinning, themes, and ZIP import/export |
| 📓 | **Vault** | Obsidian-like Markdown tree with live preview and auto-TOC |
| ✅ | **Tasks** | Subtask checklists with full version history per update |
| ✉️ | **Email** | Template composer with `{{variable}}` forms and 8 built-ins |
| 📄 | **API Docs** | Document REST endpoints, params, and responses |
| 🔖 | **Bookmarks** | Saved links organised by tag and category |
| 🎵 | **Music** | Audio library with playlists and a persistent player drawer |
| 🎧 | **TOEIC** | Listening & reading practice sets with grading and explanations |
| 📕 | **Dictionary** | Personal vocabulary store with tag search |
| 👔 | **Resume** | Frontmatter-driven CV with markdown export |
| 💬 | **Transcripts** | AI conversation logs (JSONL) with full-text search |
| 🔒 | **Lock Screen** | Frosted-glass privacy overlay, password set in Settings |

---

## Post format

Each post is a Markdown file in `posts/`:

```markdown
---
title: "Docker Compose Cheatsheet"   # required
created: 2024-01-15                  # required (YYYY-MM-DD)
updated: 2024-06-20                  # required
tags: [docker, devops]               # required — lower-cased & trimmed
category: DevOps                     # required
status: published                    # published | draft | archived
pinned: false                        # optional — pins to top of the feed
summary: "Short blurb on the card"   # optional
---

Your Markdown content starts here…
```

Pinned posts sort first, then most-recently-updated. Full Unicode (including
Vietnamese) works in titles, tags, and content.

---

## CLI

Same data as the web app: `python cli.py --help`

| Command | What it does |
|---|---|
| `new "Title" --tags a,b --cat DevOps --status published` | Create a post (defaults to draft) |
| `list --status published` | List posts (📌 pinned first) |
| `search "query" --tag docker --cat DevOps` | Full-text search |
| `serve --port 5050 --reload` | Run the web app |
| `build-index` | Rebuild tag + search indexes from disk |
| `export --out dist/site` | Export a self-contained static site |

`export` writes `index.html`, one page per post, and `style.css` with relative
links — host it anywhere or open it from disk.

---

## Keyboard shortcuts

| Key | Action |
|---|---|
| <kbd>/</kbd> | Focus search |
| <kbd>n</kbd> | New post |
| <kbd>e</kbd> | Edit the post you're viewing |
| <kbd>?</kbd> | Shortcut help |
| <kbd>Esc</kbd> | Close overlays |

---

## Configuration

`config.yaml` in the project root. Every key is optional — omitted ones fall
back to a directory of the same name under the project root.

```yaml
server:
  host: 127.0.0.1
  port: 5050

data:
  posts_dir: posts
  db_path: .kb/search.db    # SQLite FTS5 index (auto-generated, safe to delete)

ui:
  theme: vodka              # 12 built-in themes — see Settings → Appearance
  page_size: 20
```

Each feature stores data in its own directory (`notes/`, `books/`, `diagrams/`,
…), overridable via `<feature>_dir`. Rebuild indexes any time with
`python cli.py build-index`.

---

## Standalone build

```bash
./build.sh        # macOS / Linux → dist/kb-tool
build.bat         # Windows       → dist\kb-tool.exe
```

Your data directories live **next to** the executable, not inside the bundle.

---

## Development

```bash
python -m pytest tests/ -q                          # full suite
python -m pytest tests/ -q --cov=app --cov=cli      # with coverage
```

Architecture, conventions, and gotchas: **[CLAUDE.md](./CLAUDE.md)**.

React to post events without touching the core:

```python
from app.hooks import on

@on("on_post_created")            # also: on_post_updated, on_post_deleted
def notify(post):
    print(f"New post: {post.title}")
```

Handler errors are isolated — a broken plugin can't break a save.

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `No module named uvicorn` / `multipart` / `mistune` | `pip install -r requirements.txt` in the active venv |
| `TypeError: unsupported operand type(s)` on import | You're on Python 3.9 — this project needs 3.10+ |
| Search returns nothing after hand-editing files | `python cli.py build-index` |
| Tray icon doesn't appear | Needs a desktop session + `pystray`/`pillow`; use `serve` on a headless box |
| PDF pages don't render in the reader | Install `pymupdf` (bundled in the Docker image) |

knowledge_base_tool

knowledge_base_tool Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

knowledge_base_tool

knowledge_base_tool Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README