Known

Known

Remember the people you know without turning your Obsidian vault into a database you cannot read.

Known is a local-first people directory and profile viewer for Obsidian. Every person remains an ordinary Markdown note with readable YAML properties and free-form notes. Known adds the friendly interface; your vault remains the source of truth.

Known has no account, telemetry, external database, advertising, or contact-sync service.

Features

People directory

• Open a responsive people directory in a main workspace tab.
• Search names, aliases, nicknames, pronouns, relations, organizations, contact details, tags, locations, and notes about how you met.
• Sort by name, modification time, upcoming birthday, favorites, or most recent contact.
• Filter by relation, company, and tag; selecting a relation chip applies that filter immediately and case-insensitively.
• See profile photos, initials, relationships, occupations, favorites, and last-contact dates at a glance.

Person profiles

• View a polished profile without replacing Obsidian's normal Markdown editor.
• Display only populated properties, including unknown user-created YAML fields.
• Show birthdays as readable ordinal dates and calculate the age the person is turning without writing a stale age property.
• Display aliases and relationships as compact chips.
• Display tags as readable Obsidian-style pills.
• Use quick email, call, and website actions.
• Mark favorites from a profile or the command palette.
• Render the complete Markdown body with normal Obsidian links and formatting.

Safe editing

• Create people through a guided form; blank optional properties are omitted.
• Enter birthdays in separate day, month, and optional year boxes.
• Enter phone numbers with an optional one-to-three-digit calling code; blank calling codes save a leading-zero number.
• Add repeatable values through inline chips instead of line-separated textareas, including aliases, relations, tags, emails, social profiles, and custom lists.
• Enter a tag naturally, such as Human Person; Known stores human-person and continues displaying human person.
• Save existing-person changes when a field loses focus, with Saving, Saved, and Error feedback.
• Preserve unknown frontmatter and unrelated Markdown sections.
• Detect external body edits before overwriting full Markdown.
• Use structured bullets under ## Notes, or edit the complete Markdown body.
• Adopt an existing Markdown note already inside the configured People folder.
• Rename manually, automatically, or after confirmation.
• Send deleted people to Obsidian's configured trash.

Configurable fields and photos

• Built-in fields cover display/full names, aliases, nickname, pronouns, birthday, last contact, phone, email, website, social profiles, address, tags, relation, location, company, occupation, how you met, favorite status, and photo.
• Add custom text, long-text, number, boolean, date, link, select, or repeatable-list fields.
• Enable, hide, reorder, and relabel form fields without changing built-in YAML keys.
• Choose initial person-form fields from a dedicated Default person settings page. Tags are shown by default; phone and last contact are optional additions.
• Use vault image wiki-links or HTTPS photo URLs.
• Choose circle, square, rounded rectangle, rectangle, oval, or hexagon photos.

Obsidian-native

• Contextual ribbon button and command-palette actions.
• Tabbed settings pages for general options, person defaults, fields, and tags.
• Replace the active person Markdown tab with its Known profile when the contextual ribbon action is used.
• Mirror relations and locations to Obsidian tags for tag search and graph grouping, with a setting to disable synchronization.
• Theme-aware styling for light and dark themes.
• Responsive desktop, tablet, and mobile layouts.
• No Node-only runtime APIs and no production runtime dependencies.

Installation

Community plugins

After Known is accepted into the Obsidian community directory:

1. Open Settings → Community plugins → Browse.
2. Search for Known.
3. Select Install, then Enable.

Manual installation

1. Download main.js, manifest.json, and styles.css from a published GitHub release.
2. Put them in <vault>/.obsidian/plugins/known/.
3. Reload Obsidian.
4. Enable Known under Community plugins.

Quick start

1. Select the people icon in the ribbon or run Open people.
2. Select Add person and enter a name.
3. Add any useful fields and notes, then select Create.
4. Open the generated Markdown whenever you want direct access to the underlying data.

The default storage folder is People. A note is recognized when it is inside that folder (or a subfolder) and contains type: person plus a non-empty name.

Person note format

---
type: person
name: Ada
full-name: Ada Lovelace
aliases:
  - Augusta Ada King
birthday: "1815-12-10"
last-contact: "2026-08-09"
phone:
  - "+442000000000"
email:
  - [email protected]
website: https://example.com
photo: "[[Attachments/People/Ada.jpg]]"
relation:
  - "#Friend"
location: "#London"
tags:
  - Friend
  - London
favorite: true
---

## Notes

- Met through the analytical society.

Blank optional fields are removed. Unknown properties are preserved. Full birthdays use YYYY-MM-DD; birthdays without a known year use --MM-DD. Profiles show the latter as, for example, 25th August, and full dates as 25th August (Turning 26).

By default, Known stores relation and location values with a leading # and mirrors their normalized names into the standard tags property. Known hides the marker in its interface. This keeps the source Markdown useful for Obsidian tag search and graph grouping while preserving dedicated relation and location properties.

In structured-notes mode, Known owns the exact ## Notes section and preserves other Markdown sections. Full-Markdown mode edits everything below the frontmatter.

Commands

• Open people — open the active person's profile, or the directory otherwise.
• Create person — open the new-person form.
• Add current note to Known — add type: person and a name to a Markdown note already inside the People folder.
• Open current person in Known — open the active indexed person in the profile UI.
• Toggle favorite for current person — add or remove favorite status.

Known does not assign default hotkeys. Configure your own under Settings → Hotkeys.

Settings

• People folder
• Photo shape
• Default directory sort
• Hidden or N/A display for unknown birthdays
• Structured-bullet or full-Markdown notes editor
• Manual, automatic, or prompted filename changes
• Relation and location tag synchronization
• Default person fields
• Built-in and custom field order, labels, availability, and default visibility

Changing the people folder reindexes the new location but never silently moves existing notes.

Privacy and security

Known reads and writes files only in the active vault through Obsidian's public APIs. It does not collect or transmit vault data. If a person uses an HTTPS photo URL, Obsidian loads that image directly from the remote host while the profile is visible; Known does not download or cache it.

Never include real personal data in public bug reports, screenshots, or test fixtures. See SECURITY.md for private vulnerability reporting.

Development

Requirements: Node.js 20 or newer and npm.

npm ci
npm run dev

The complete verification command runs strict TypeScript checking, Obsidian-aware ESLint rules, unit tests, a production build, and release-asset validation:

npm run check

For local testing, copy or symlink the repository into <vault>/.obsidian/plugins/known, reload Obsidian, and enable Known.

Releasing

1. Run npm version patch, npm version minor, or npm version major as appropriate. The version script synchronizes manifest.json and versions.json.
2. Push the commit and an exact semantic-version tag without a v prefix, for example 1.3.0.
3. GitHub Actions verifies the tag, builds the plugin, attests the assets, and creates a draft release containing main.js, manifest.json, and styles.css.
4. Review and publish the draft release before submitting or updating Known in the Obsidian directory.

See CONTRIBUTING.md and CHANGELOG.md for more information.

Planned work is tracked in DEVELOPMENT.md.

License

Known is available under the MIT License.

Known is created and maintained by @NameIsKyro.