version: "1.0.1" name: personal-knowledge-capture description: 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.

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 <folder>.
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:

python3 scripts/personal_knowledge_capture.py add-watch --path "$HOME/research" --tags "ai,research"

Scan registered watch paths:

python3 scripts/personal_knowledge_capture.py scan

Scan and write today's Markdown summary:

python3 scripts/personal_knowledge_capture.py summarize

Capture an explicitly provided URL:

python3 scripts/personal_knowledge_capture.py capture-url --url "https://example.com/article"

Use --state-dir <path> only when a user asks to place runtime state somewhere specific.

Persistence

The helper stores local runtime artifacts under:

~/.codex/state/personal-knowledge-capture/
  knowledge_capture.db
  runs/
  knowledge-notes/

SQLite tables:

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:

knowledge-notes/YYYY-MM-DD-summary.md

The generated note must keep this structure:

# 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 <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 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; 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.