Metadata-Version: 2.4
Name: kindred-keeper
Version: 0.1.0
Summary: A local-first relationship memory desk for thoughtful follow-ups.
Author: Kindred Keeper maintainers
License-Expression: MIT
Keywords: relationships,personal-crm,local-first,planning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Kindred Keeper

Kindred Keeper is a private, local-first relationship memory desk for thoughtful follow-ups. Add people you care about, jot down small details after calls or visits, and it builds a practical plan for check-ins, promises, birthdays, and meaningful moments.

Everything runs on your computer with the Python standard library. There is no account, upload, telemetry, or hosted database.

![Kindred Keeper dashboard](docs/screenshot.svg)

## Features

- Local browser app backed by a JSON file on your machine.
- Contact profiles with relationship, cadence, interests, and last touchpoint.
- Note analysis that extracts interests, promises, dates, sentiment, and relationship signals.
- Lightweight local classifier trained on celebration, support, commitment, and interest examples.
- Planning workflow that ranks overdue follow-ups, open commitments, and upcoming dates.
- Suggested message drafts that stay specific to the person and the reason for reaching out.
- Copy-ready weekly relationship plan.
- Seeded demo workspace so the full workflow is visible on first launch.

## Installation

Requirements:

- Python 3.10 or newer

```bash
git clone https://github.com/iwaheedsattar/kindred-keeper.git
cd kindred-keeper
python3 app.py
```

Open [http://127.0.0.1:8768](http://127.0.0.1:8768).

To use a custom local data file:

```bash
python3 app.py --data ./my-kindred-data.json
```

## Example Usage

1. Launch the app with `python3 app.py`.
2. Review the seeded relationship plan.
3. Add a person you want to stay close to.
4. Save a note such as:

```text
Lina loves Korean food and ceramics. Promised to send the podcast link. Her recital is Jul 16.
```

5. Review the follow-up plan and copy the weekly plan into your calendar or notes app.

## How It Works

Kindred Keeper uses a small local planning pipeline:

1. Notes are tokenized and scored with a compact multinomial classifier.
2. Extractors find promises, dates, and interest phrases.
3. Each contact receives warmth and attention scores based on cadence, open commitments, support signals, and recent notes.
4. The planner ranks next actions and writes a short message draft for each one.

The pipeline is intentionally small and transparent so personal relationship notes stay local and understandable.

## Development

```bash
python3 -m unittest discover -s tests
python3 app.py --no-open --data ./.kindred-keeper-data.json
```

Package build:

```bash
python3 -m build --no-isolation
```

## Project Layout

- `kindred_keeper/engine.py` contains note analysis, scoring, and planning.
- `kindred_keeper/storage.py` manages the local JSON workspace.
- `kindred_keeper/server.py` serves the local web app and JSON API.
- `static/` contains the browser UI.
- `tests/` covers extraction, summary scoring, and action planning.

## Roadmap

- Calendar export for planned check-ins.
- Import from a simple contacts CSV.
- Reminder notifications in a desktop wrapper.
- Optional encrypted data file.
- Better recurring-date handling for birthdays and anniversaries.

## License

MIT
