OKEEF
Jojo's personal knowledgebase (Open Knowledge Format + PARA method).
Open source Repository Open in the app JSON README (API)
About
# OKEEF
Personal second-brain knowledgebase, built on Google's Open Knowledge Format (OKF v0.1) and organized with the PARA method.
# Sections
* [Projects](/Projects/index.md) - active, time-bound efforts with a defined outcome.
* [Areas](/Areas/index.md) - ongoing responsibilities with no end date.
* [Resources](/Resources/index.md) - reference material and topics of interest.
* [Archives](/Archives/index.md) - inactive items from the other three sections.
# How this bundle is built
New material is dropped into `_inbox/`. A local pipeline (Ollama + a small classifier model) extracts, classifies, and files it into the correct section above as a conformant OKF concept document, then commits the result to git. See `log.md` for the change history.
Details
- Kind
- OKF bundles
- Topic
- Version control
- Publisher
- cakkes
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Last push
- 2026-08-01T03:52:50Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-08 16:04:09
- Updated
- 2026-09-08 16:04:09
- Origin id
cakkes/OKEEF:Knowledgebase/index.md
README
# OKEEF
A personal, local-first knowledgebase ("second brain") built on Google's
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
(OKF v0.1) and organized with the [PARA method](https://fortelabs.com/blog/para/)
(Projects / Areas / Resources / Archives).
Drop files into `App\_inbox\`; a local pipeline (Ollama + a small classifier model)
extracts, classifies, and files them as conformant OKF markdown documents, then
commits the result to git. The whole bundle is queryable through
[Open WebUI](https://openwebui.com), a local chat UI with retrieval-augmented
generation (RAG), so you can ask questions grounded in your own notes.
Everything runs entirely locally -- no data leaves the machine, no cloud APIs
involved.
## Prerequisites
- Windows 11 (this repo's automation is Windows-specific; see [Cross-platform
notes](#cross-platform-notes) below for adapting it elsewhere)
- PowerShell
- A GPU with at least ~4GB VRAM is enough for the default models (CPU-only also
works, just slower)
`setup.ps1` installs the rest (Git, Python 3.11, Ollama) via `winget` if they're
not already present.
## Setup
```powershell
git clone <this-repo-url> D:\OKEEF
cd D:\OKEEF
.\setup.ps1
```
`setup.ps1` is idempotent -- safe to re-run any time, including after a partial
failure. It:
1. Installs Git / Python 3.11 / Ollama if missing.
2. Creates `.venv` (the ingestion pipeline) and installs its dependencies.
3. Pulls the two required Ollama models: `qwen2.5:3b-instruct` (classification)
and `nomic-embed-text` (embeddings).
4. Creates the PARA folder skeleton if this is a fresh checkout without content yet.
5. Prompts for an admin email/name on first run and generates a random admin
password, saved to `.env` (gitignored, machine-specific, never printed to the
terminal).
6. Creates `.venv-webui` and installs Open WebUI.
7. Starts Open WebUI once to complete first-run setup **entirely headlessly, no
browser needed**: creates the admin account, enables API keys, points the
embedding engine at Ollama, sets chunk size/overlap and hybrid search, and
creates the "OKEEF Bundle" Knowledge collection -- all via Open WebUI's REST API.
8. Backfills any existing content into that Knowledge collection.
9. Registers the inbox watcher as a Windows Scheduled Task (see below -- this step
may need to be run separately if it fails with "Access is denied").
### If Scheduled Task registration fails
`Register-ScheduledTask` (and the legacy `schtasks.exe`) can fail with "Access is
denied" depending on how restrictive the current process token is, even for an
Administrator account under UAC. If `setup.ps1` reports this, run the one
remaining step yourself in a normal PowerShell window:
```powershell
.\App\scripts\register-tasks.ps1
```
## Day-to-day use
- **Add something to your knowledgebase**: drop a `.txt`, `.md`, `.pdf`, or
`.docx` file into `App\_inbox\`. If the watcher is running (it auto-starts at
login once the Scheduled Task is registered), it's picked up within a couple
of seconds, classified, filed into the right PARA folder as an OKF document,
and committed to git.
- **Start the ingestion service on demand**: double-click
`App\scripts\Start-Service.bat` -- runs the same catch-up-scan + watch +
commit + sync as the scheduled task, with no console window left open.
Doesn't touch Open WebUI.
- **File something you added by hand**: if you drop a raw file directly into
`Knowledgebase\Projects\`, `Areas\`, `Resources\`, or `Archives\` (instead of
`App\_inbox\`), it bypasses the pipeline entirely until you run the PARA
scanner: double-click `App\scripts\Scan-ParaFolders.bat` (or `okeef
scan-para`). It finds every such file, OKF-ifies it, and commits it --
**in the exact folder you put it in**, never reclassified into a different
bucket.
- **Chat with your knowledgebase**: run `.\App\scripts\start-openwebui.ps1`, then
open <http://localhost:8080>. Not auto-started at login -- it's a manual
run/shortcut since it's only needed while actively chatting.
- **Process one file manually** (without the watcher): `okeef process-file <path>`
- **Pause ingestion**: stop the "OKEEF Watcher" scheduled task
(`Stop-ScheduledTask -TaskName "OKEEF Watcher"`), or just don't drop files.
- **Toggle review-before-commit mode**: set `AUTO_COMMIT=false` in `App\.env`. New
drops are staged under `App\_staging\<id>\` (a `draft.md` you can hand-edit --
including the proposed PARA bucket/folder, via the `_para_bucket`/
`_folder_slug` frontmatter keys -- plus a `proposal.json` for reference)
instead of being filed immediately. Review with `okeef list-staged`, then
`okeef approve <id>` to file and commit it (add `--approved-by "Your Name"`
to record it in the commit trailer). The PARA scanner always files and
commits immediately -- it doesn't use this review flow.
- **Reprocess a quarantined file**: failed extractions/classifications land in
`App\_quarantine\` with a `<name>.reason.txt` explaining why. Fix the
underlying issue (or the file itself) and drop it back into `App\_inbox\`.
- **Re-sync Open WebUI's Knowledge collection**: `okeef resync` -- walks every
concept doc under the PARA folders and re-uploads it. Useful after wiping
`App\data\openwebui\` or if a sync failed partway (sync failures don't break
ingestion; the git commit is the source of truth, and `resync` catches up).
## Known issues
- **"Failed to attach file... 400: We could not find what you're looking
for"** on `okeef resync` or a sync warning in `App\logs\watcher.log`: the
installed Open WebUI version has been observed to make an existing Knowledge
collection unreachable via its API after several rapid restarts, even though
the row is still present and intact in `App\data\openwebui\webui.db` (confirmed
by inspecting the SQLite file directly). The fix is to create a fresh
collection and point `OPENWEBUI_KNOWLEDGE_ID` at it:
```powershell
# after signing in and getting $headers (see setup.ps1 for the exact calls)
$k = Invoke-RestMethod -Uri "http://localhost:8080/api/v1/knowledge/create" -Headers $headers -Method Post `
-Body (@{name="OKEEF Bundle"; description="Personal OKF/PARA knowledgebase"} | ConvertTo-Json) `
-ContentType "application/json"
# replace OPENWEBUI_KNOWLEDGE_ID in .env with $k.id, then: okeef resync
```
This doesn't lose any content -- the git-committed OKF documents are the
source of truth; `resync` re-populates whatever collection ID you point it at.
## How it's built
```
D:\OKEEF\
├── Knowledgebase\ the knowledge content itself (bundle root)
│ ├── index.md, log.md hand-curated; never auto-touched beyond
│ │ log.md's dated entries
│ └── Projects\ Areas\ Resources\ Archives\
│ PARA sections; each subfolder's index.md is
│ auto-generated between marker comments
├── App\ the pipeline application + all runtime state
│ ├── src\okeef\ the ingestion pipeline (see module docstrings)
│ ├── scripts\ register-tasks.ps1, start-openwebui.ps1,
│ │ Start-Service.bat, Scan-ParaFolders.bat
│ ├── config\config.yaml shared config (models, chunk size, PARA buckets)
│ ├── .env machine-specific: AUTO_COMMIT override,
│ │ Open WebUI admin/API credentials, knowledge_id
│ ├── .venv\, .venv-webui\ the two venvs (pipeline; Open WebUI)
│ ├── _inbox\ drop files here
│ ├── _staging\ review-mode drafts (AUTO_COMMIT=false)
│ ├── _quarantine\ failed extractions/classifications
│ └── data\openwebui\ Open WebUI's own state (regenerable via
│ resync, except chat history itself)
├── INITDOCS\, README.md, CLAUDE.md, LICENSE
└── setup.ps1 bootstrap entry point (run this first)
```
Each `App/src/okeef/*.py` module has a docstring explaining its role;
`pipeline.py` is the best starting point -- it's the orchestrator tying
extraction, classification, writing, indexing, committing, and syncing
together.
## Smoke test
After setup, confirm everything works end to end:
```powershell
"Testing OKEEF." | Out-File App\_inbox\smoke-test.txt -Encoding utf8
# wait a few seconds for the watcher (or run: okeef process-file App\_inbox\smoke-test.txt)
git log --oneline -1 # should show a new "ingest(...)" commit
```
Then open <http://localhost:8080> (after running `App\scripts\start-openwebui.ps1`)
and ask a question about the file you just added -- the answer should be
grounded in it and cite the source.
## Cross-platform notes
The pipeline code (`App/src/okeef/`) is pure Python and portable as-is. What's
Windows-specific:
- `pythonw.exe` (no-console launch) -- macOS/Linux don't need an equivalent;
just run the command directly or via a `systemd`/`launchd` unit.
- Task Scheduler (`App\scripts\register-tasks.ps1`) -- replace with a `launchd`
`.plist` (macOS, `RunAtLoad`) or a `systemd --user` service / cron `@reboot`
entry (Linux) running `python -m okeef.cli watch`.
- `winget` in `setup.ps1` -- swap for `brew` (macOS) or your distro's package
manager for installing Git/Python/Ollama; Ollama and Open WebUI both ship
native installers for macOS/Linux too.
- Path handling in the pipeline itself already uses `pathlib`, so it doesn't
need changes.