pathnote

name	pathnote
description	Path knowledge management CLI — attach semantic metadata to files and directories with inheritance, glob rules, move detection, source tracking, and staleness decay
version	0.3.5
commands	["pn"]

pathnote — Agent Guide

pathnote is a path knowledge management tool. Use it to record and query semantic information about paths across projects, avoiding repeated discovery of the same context.

All data lives in ~/.pathnote/db.sqlite — zero intrusion into project directories.

Core Concepts

View

Run pn view <path> to get merged metadata: tags, conv, note, globs, source, verified_at, staleness. Child paths automatically inherit parent metadata.

/project       → tags: [python], conv: "ML project"
/project/src   → tags: [fastapi], conv: "API layer"

pn view /project/src/main.py
→ Tags:    fastapi, python         ← inherited python, local fastapi
→ Conv:    application entry       ← local overrides parent
→ Source:  agent                   ← source label
→ Fresh:   verified today          ← staleness status

Inheritance Rules

Field	Behavior	Notes
tags	Union (ancestor + local, deduped)	Don't re-tag what parents already have
conv	Local overrides ancestor	Local conv takes precedence
note	Local overrides ancestor	Same as conv
globs	Not inherited	Only applies to direct children of defining directory
source	Not inherited	Each record tracks its own source
verified_at	Not inherited	Each record tracks verification time

Source

Each path knowledge entry has a source label indicating confidence:

Source	Value	Confidence	When set
User stated	user	High	pn set default
Agent inferred	agent	Medium	pn note default
Pattern matched	inferred	Low	Future auto-detection

pn note only sets source on new entries or when explicitly passed --source.

Staleness

verified_at tracks when knowledge was last confirmed correct. pn view shows staleness:

Status	Condition	Display
fresh	verified ≤ 7 days ago	Fresh: verified 2 days ago
stale	verified 7-30 days ago	Stale: verified 12 days ago
old	verified > 30 days ago	Old: verified 45 days ago

Use pn verify <path> to confirm knowledge is still correct.

Glob Rules

Directory-level filename pattern matching for auto-labeling unregistered children. Registered entries are unaffected.

pn set /project/src --glob "*.go:tags=go,conv=Go source"

Important: globs do not inherit. A glob on /project/src only affects its direct children.

Remove glob: pn set /path --glob "-*.py"

Path Status

pn view <path> --status returns four states:

Status	Meaning
ok	Registered, hash unchanged
changed	Registered, hash changed
orphan	Registered, path doesn't exist on filesystem
new	Not registered

Commands

init — Initialize database

$ pn init
Initialized pathnote at ~/.pathnote/db.sqlite (schema v2)

Run once before first use. If database exists, does nothing.

--force backs up existing database and creates fresh one.

set — Set metadata

Set or update metadata for a path. Supports tags, conv, note, glob, source. Creates orphan entry if path doesn't exist.

$ pn set /project/src --tags +go,+api --conv "HTTP API layer"
Updated /project/src
  tags: api, go
  conv: HTTP API layer

Tags syntax:

• +tag append, -tag remove, no prefix = replace all
• Any tag with prefix triggers incremental mode
• No prefixes = replace mode

pn set /path --tags +go,+api      # incremental: append
pn set /path --tags go,api        # replace: set to [api, go]
pn set /path --tags -old,+new     # incremental: remove old, append new

--clear: Clear specified fields: --clear=tags,note,conv,globs

--source: Default user. Only overwrites existing source when flag explicitly changed.

note — Append observation

Lightweight entry for appending notes (newline-separated). Default source=agent.

$ pn /project/config "Changing this breaks VPN"
$ pn note /project/config "Another observation" --tags +large

	pn note	pn set --note
Note behavior	Append	Replace
Source default	agent	user

verify — Confirm knowledge

Updates verified_at, resets staleness to fresh.

$ pn verify /project/config
Verified /project/config

view — View merged knowledge

View merged metadata for a path (inheritance auto-applies). Supports modes:

Full (default):

$ pn view /project
Path:    /project
Type:    directory
Tags:    backend, go
Conv:    Backend service main directory
Fresh:   verified 2 days ago

Status only:

$ pn view /project/src --status
/project/src  ok

Inheritance chain:

$ pn view /project/src -i

JSON output: -j

No path argument defaults to current working directory.

ls — List children

List filesystem children of a directory with pathnote status.

$ pn ls /project
✓ src          [registered]
  Makefile     [unregistered]

• -r recursive
• --local show local tags (default: resolved tags)
• -j JSON

No path argument defaults to cwd.

find — Search paths

Search registered paths. Multiple conditions = AND logic. At least one filter required.

$ pn find --tags backend
$ pn find --source agent
$ pn find --orphan
$ pn find --stale

Flag	Match
--tags	Exact match resolved tags; - prefix excludes
--conv	Substring match, case-insensitive
--path	Substring match, case-insensitive
--note	Substring match, case-insensitive
--source	Exact match
--stale	Verified > 7 days ago or empty
--not-stale	Verified ≤ 7 days ago
--orphan	Path doesn't exist on filesystem
--after/--before	Update time range

reindex — Update hashes, detect moves

Scan registered paths, update hashes, detect moved/orphaned entries. Auto-migrates when hash matches new location.

$ pn reindex /project

Paths still on filesystem auto-update verified_at.

rm — Delete entry

$ pn rm /project/old_file.go
$ pn rm /project/old_dir --cascade

Non-cascade refuses if descendants exist.

status — Global stats

$ pn status
Pathnote: ~/.pathnote/db.sqlite
  Registered paths: 42
  Files: 38
  Directories: 4

MCP Server

pathnote runs as MCP stdio server for AI agents.

Configure Claude Code

claude mcp add --transport stdio -s user pathnote -- pn mcp

Configure Hermes Agent

mcp_servers:
  pathnote:
    command: pn
    args: ["mcp"]
    timeout: 30

Available MCP Tools (8)

Tool	Command	Description
view	pn view	Get merged metadata. Call before reading files in unfamiliar areas.
note	pn note	Append observation. For non-obvious semantics, constraints, gotchas.
set	pn set	Register or overwrite metadata. Use on first entry or when purpose changes.
verify	pn verify	Mark knowledge as still valid. Resets staleness.
find	pn find	Search by tags, conv, note, source, staleness, or orphan status (AND).
ls	pn ls	List filesystem children with pathnote status.
reindex	pn reindex	Update hashes and detect moved/orphaned paths.
rm	pn rm	Delete path record (not the file). cascade=true removes descendants.

Notes

• ls shows filesystem children, annotates registered status
• set on non-existent path creates orphan entry
• glob rules don't inherit
• view --status needs reindex to detect content changes
• tags use +/- prefix for add/remove, no prefix = replace
• source and verified_at don't inherit
• note appends, set --note replaces
• note doesn't overwrite existing source unless --source passed
• reindex auto-updates verified_at for existing paths
• PATHNOTE_DB env var for custom database location