A smart notes app that surfaces relevant saved content when you need it, solving the problem of orphaned notes and lost ideas.

Quick Start • Features • Examples • Contributing

What is this?

Personal Knowledge Retrieval System is a CLI‑based notes app that helps knowledge workers, researchers, writers, and students capture ideas and instantly retrieve the most relevant ones when they need them. It stores notes locally with rich metadata and provides fast, fuzzy search over your personal knowledge base.

Example:

$ pkrc add-note "Reviewed paper on transformers" --tag research --source "https://arxiv.org/abs/1706.03762"
Note created: note_9f3b2a1c

Problem

People save dozens of notes, article highlights, screenshots, and research snippets but can never find them when needed. Notes apps become digital junk drawers full of half-finished thoughts that are effectively lost. There's a need for intelligent organization that makes saved information actually retrievable and useful.

Features

Feature	Description
Note Taking	Capture text snippets, highlights, and screenshots with tags, timestamps, and source URLs.
Full‑Text Search	Index all note content and return results sorted by relevance using fuzzy matching.
Tag & Date Filters	Narrow searches by one or more tags and/or date ranges.
Export/Import	Backup notes to JSON or import external JSON while preserving original IDs and tags.
Offline‑First	All data resides in a local SQLite file; no network calls are required.
Metadata Attachment	Each note stores UUID, content, tags, created/updated timestamps, and optional source URL.
CLI Interface	Simple commands like add-note, search, export, and import powered by Click.
Tested Core	Pytest suite validates CRUD operations, search ranking, and data persistence.

Quick Start

1. Clone the repository:

   git clone https://github.com/yourusername/personal-kr.git
   cd personal-kr

2. Install the package in editable mode:

   pip install -e .

3. Add your first note:

   pkrc add-note "Welcome to my knowledge base" --tag intro

   Expected output:

   Note created: note_4d5e6f7a
   

Examples

Adding a tagged note

$ pkrc add-note "Meeting agenda: discuss sprint goals" --tag work --source "https://example.com/meeting"
Note created: note_88a1b2c3

Searching by tag and date

$ pkrc search --tag work --since "2024-09-01"
1. note_88a1b2c3 - Meeting agenda: discuss sprint goals (score: 0.92)
2. note_3f4a5b6c - Reviewed budget report (score: 0.78)

Exporting and re‑importing

$ pkrc export --format json --output backup.json
Exported 27 notes to backup.json

$ pkrc import --input backup.json
Imported 27 notes; 0 duplicates skipped

File Structure

Personal Knowledge Retrieval System/
  src/                  # Core source code
    personal_kr/        # Package
      cli.py            # Command‑line interface
      storage.py        # Storage layer (SQLite + JSON)
      models/           # Pydantic models
        notemodel.py
        querymodel.py
      api/              # Internal API helpers
      __init__.py
  tests/                # Test suite
    test_cli.py
    test_storage.py
    test_models.py
    test_api.py
  assets/               # Infographic used in README
  data/                 # Storage directory (created automatically)
  screenshots/          # Example CLI output files
  pyproject.toml        # Project configuration and dependencies
  LICENSE
  README.md

Tech Stack

Technology	Purpose
Python 3.11+	Core language
Click	Building the CLI
Pytest	Running tests
Pydantic	Data validation for Note and Query models
SQLite (via storage.py)	Persistent local storage
Standard Library	File handling, datetime, JSON

Contributing

Fork the repo, create a feature branch, make changes, run pytest, and submit a pull request.

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio