# Personal Knowledge Capture > Capture and synthesize local or explicitly provided web sources into cited Markdown notes. Use to register a research folder, summarize new or modified Markdown/TXT/PDF/DOCX files, deduplicate sources, surface conflicting claims, capture a provided URL or persist course knowledge notes with provenance. Do not use to move or organize files or schedule workflows. - Skill: `prompthon-io/personal-knowledge-capture` (Agent Skill, multi-file: 12 files) - Install (CLI): `npx skillmds@latest add prompthon-io/personal-knowledge-capture` - Raw SKILL.md: https://api.skillmd.com/api/skills/prompthon-io/personal-knowledge-capture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: Prompthon-IO (https://skillmd.com/u/prompthon-io) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/prompthon-io/personal-knowledge-capture --- # Personal Knowledge Capture Use this skill to maintain local-first personal knowledge notes from user-approved sources. Register folders only when the user names them, scan registered folders on demand, extract text from supported file types, and write cited Markdown notes. For the human-facing overview, read `README.md`. For supported file type details, read `references/supported-file-types.md` when extraction behavior matters. ## Safety Rules - Scan only folders the user explicitly names or previously registered with `add-watch`. - Do not upload local files to external services unless the user explicitly asks and credentials are available. - Preserve source files exactly; never move, rewrite, delete, or rename them. - Keep runtime databases, scan artifacts, and generated notes outside git unless the user explicitly asks for sample artifacts. - Ground generated notes in source references. Do not present uncited claims as coming from the captured files. - Treat `capture-url` as opt-in only: fetch only URLs the user explicitly provides. ## Default Workflow 1. Register a watch path with `scripts/personal_knowledge_capture.py add-watch --path `. 2. Run `scripts/personal_knowledge_capture.py scan` when the user wants a detection preview only; this does not mark files as captured. 3. Run `scripts/personal_knowledge_capture.py summarize` when the user wants a dated Markdown note; this command performs its own scan. 4. Review the generated note and refine summaries with Codex when deeper synthesis is needed. 5. Report source paths, skipped files, and the note path to the user. ## Commands Resolve `scripts/personal_knowledge_capture.py` relative to this skill directory. When running from an installed Codex copy, that is usually: ```bash python3 scripts/personal_knowledge_capture.py add-watch --path "$HOME/research" --tags "ai,research" ``` Scan registered watch paths: ```bash python3 scripts/personal_knowledge_capture.py scan ``` Scan and write today's Markdown summary: ```bash python3 scripts/personal_knowledge_capture.py summarize ``` Capture an explicitly provided URL: ```bash python3 scripts/personal_knowledge_capture.py capture-url --url "https://example.com/article" ``` Use `--state-dir ` only when a user asks to place runtime state somewhere specific. ## Persistence The helper stores local runtime artifacts under: ```text ~/.codex/state/personal-knowledge-capture/ knowledge_capture.db runs/ knowledge-notes/ ``` SQLite tables: ```sql watch_paths(id, path, tags, created_at, last_scanned_at) documents(id, path_or_url, title, hash, source_mtime, captured_at, summary_path) ``` `source_mtime` is an implementation addition beyond the base issue schema. It stores the source file's last-modified timestamp so the scanner can skip files whose content hash and mtime are both unchanged, reducing redundant re-extraction. ## Markdown Output Daily summaries are written to: ```text knowledge-notes/YYYY-MM-DD-summary.md ``` The generated note must keep this structure: ```md # Summary ## New Files ## Key Insights ## Actionable Notes ## Open Questions ## Source References ``` If Codex rewrites or enriches the summary, preserve the section headings and keep every source-grounded point tied to `Source References`. ## Supported Sources - Markdown: `.md`, `.markdown` - Plain text: `.txt` - DOCX: basic built-in text extraction from `word/document.xml` - PDF: supported when the optional `pypdf` dependency is installed - URLs: supported only through explicit `capture-url --url ` For unsupported or failed extraction, report the skipped source and reason instead of silently dropping it. ## Response Pattern When reporting results to the user, include: - registered or scanned paths - number of new, modified, and skipped sources - generated note path - skipped files and extraction reasons - source-reference expectations for any summary text ## Professional AI Agent Course adapter (Understand) For Lesson 2 learning examples, follow the course README links and use `course_knowledge.py` directly; these exercises do not require registering watch paths. Use a separate note id for each scenario and the same id for repeated runs within that scenario. When students customize rules, edit only the seeded scenario's `rules.json` and pass it with `--rules`; preserve the shared defaults. For classroom work, synthesis requests, or a storage-mode request, use `scripts/course_knowledge.py` in this same package. The original helper remains the standalone baseline. Extract and deduplicate selected sources into a cited note, flag contradictions and track changes. Never relocate source files. Read the course section of `README.md`, then use the shared setup and synthetic fixtures. Put storage/context flags before the command. Keep source files and recovery journals local, honor all approval gates, and verify canonical reads after persistence. Remote mode requires the provisioned [contract](references/persistence-contract.md); a missing backend is a dependency failure, never a reason to invent credentials or silently use local state. Only the named folder is scanned; source files are never modified. Incremental extraction caches remain local and are keyed by content hash and modification time. Remote notes contain derived extractive summaries and source metadata, not original binaries or the complete extracted text. `--share-content` is an explicit extra opt-in for extracted text; review privacy first. The deterministic conflict detector only recognizes field:value disagreements and does not assign authority automatically.