portable-agent-layer 0.41.1 → 0.42.0

package/.husky/install.mjs

@@ -0,0 +1,8 @@
+import { existsSync } from 'node:fs'
+
+if (process.env.CI === 'true' || process.env.NODE_ENV === 'production' || !existsSync('.git')) {
+  process.exit(0)
+}
+
+const husky = (await import('husky')).default
+console.log(husky())

package/README.md

@@ -84,6 +84,7 @@ pal cli status        # check your setup
 | `pal cli doctor` | Check prerequisites and system health |
 | `pal cli migrate` | Run pending data migrations (non-destructive) |
 | `pal cli usage` | Summarize token usage and estimated cost |
+| `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 
 ### Target flags
 
@@ -159,7 +160,7 @@ PAL ships with built-in skills that extend your agent's capabilities:
 | `council` | Multi-perspective parallel debate on decisions |
 | `create-pdf` | Render structured content into a PDF |
 | `create-skill` | Scaffold a new skill from a description |
-| `extract-entities` | Extract people and companies from content |
+| `entities` | Detect, save, and query people & companies in the personal knowledge graph |
 | `extract-wisdom` | Extract structured insights from content |
 | `first-principles` | Break down problems to fundamentals |
 | `fyzz-chat-api` | Query Fyzz Chat conversations via API |

package/assets/skills/analyze-youtube/SKILL.md

@@ -23,7 +23,7 @@ Follow the user's request. Common tasks:
 
 - **Summarize** the video content
 - **Answer a specific question** about what's shown or discussed
-- **Extract entities** (defer to /extract-entities if installed)
+- **Extract entities** (defer to /entities if installed)
 - **Extract wisdom** (defer to /extract-wisdom if installed)
 - **Compare** with other content
 

package/assets/skills/entities/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: entities
+description: Maintain the personal knowledge graph of people and companies. Detect named entities in any content (article, video, paste, conversation), upsert them to ~/.pal/memory/knowledge/, and surface what's already known. Use proactively whenever named entities appear — don't wait to be asked.
+argument-hint: <content, URL, or pasted text>
+---
+
+Detect, persist, and query people and companies referenced in $ARGUMENTS.
+
+The default workflow is **extract → save → show summary**, in that order. Saving is not optional: persistence is the point of the skill. Skip the save step only if the user explicitly said "don't save", "just look", or similar.
+
+## 1. Extract
+
+Read/fetch the content and extract ALL people and companies mentioned.
+
+### People
+
+For each person, extract:
+- **name**: Full name
+- **role**: author | subject | mentioned | quoted | expert | interviewer | interviewee
+- **title**: Job title (null if unknown)
+- **company**: Company affiliation (null if unknown)
+- **social**: twitter (@handle), linkedin (URL), email, website — null if unknown
+- **context**: Why this person is mentioned and their relevance
+- **importance**: primary (central to content) | secondary (supporting) | minor (brief mention)
+
+### Companies
+
+For each company/organization, extract:
+- **name**: Official name
+- **domain**: Primary website domain (e.g. "anthropic.com", null if unknown)
+- **industry**: Classification (AI, security, fintech, healthcare, etc.)
+- **context**: How and why mentioned
+- **mentioned_as**: subject | source | example | competitor | partner | acquisition | product | other
+- **sentiment**: positive | neutral | negative | mixed
+
+### Extraction guidelines
+
+- Accuracy over quantity — use null for unknown fields, never guess
+- Include authors, subjects, quoted individuals, and anyone significantly mentioned
+- For research papers: all authors get "author" role
+- For interviews: distinguish interviewer vs interviewee
+- Universities and research institutions count as companies
+- Extract social handles from bios, signatures, or text body
+- Context fields should explain relevance, not just repeat the mention
+
+### Output shape
+
+```json
+{
+  "people": [...],
+  "companies": [...]
+}
+```
+
+## 2. Save (default)
+
+Immediately persist the extracted JSON. Do not ask first — saving is the default:
+
+```bash
+echo '<the JSON output>' | pal cli knowledge ingest --source "<URL or content origin>"
+```
+
+The CLI writes one markdown file per entity under `~/.pal/memory/knowledge/{People,Companies}/<slug>.md`, preserving every extracted field (role, title, social, context, importance for people; domain, industry, sentiment, mentioned_as for companies) as frontmatter. When a person record includes a `company`, a `part-of` typed edge is auto-created from the person to the company (the company is stub-created if it doesn't exist yet). Each ingestion appends a per-source log section to the entity's body so the same source can be re-ingested safely (idempotent on `--source`).
+
+The CLI prints a JSON summary of `{created, updated, slugs}` counts per domain.
+
+**Opt-out:** if the user explicitly said not to save (e.g. "who's mentioned in this email — don't store anything"), skip step 2 entirely and just show the extracted JSON.
+
+## 3. Query (read-back)
+
+Before scraping a known source, or after saving, surface what's already on file:
+
+```bash
+pal cli knowledge search "<name>"   # substring across title, tags, body
+pal cli knowledge show <slug>       # full entity (frontmatter + body)
+pal cli knowledge graph <slug>      # related entities (BFS, default 2 hops)
+pal cli knowledge ls People         # list a domain
+pal cli knowledge stats             # counts, hubs, isolated nodes
+pal cli knowledge find <tag>        # entities tagged with <tag> (topic: prefix transparent)
+```
+
+Use `search` before extracting to detect duplicates; use `show` to confirm a save landed correctly; use `graph` to surface relationships the user may have forgotten.
+
+## Tag conventions (important)
+
+Tags do two different jobs in the store, and PAL keeps them separated so the graph stays meaningful:
+
+| Tag form | Purpose | Example | Generates graph edges? |
+|---|---|---|---|
+| `topic:<token>` | **Facet** — for filtering / `find` | `topic:ai`, `topic:consulting` | **No** — two entities sharing `topic:ai` do NOT get linked |
+| Unprefixed | **Structural** — for navigation | `acme-labs`, `customer` | Yes — co-occurrence creates tag edges |
+
+**Industry inheritance.** When ingest sees a company `industry`, it splits the string on whitespace and `/` and writes `topic:<token>` tags for each piece. When a person is linked to a company, the person inherits **only** the company's `topic:*` tags — never structural ones. This keeps `find ai` useful (it surfaces every AI-industry company + their employees) without creating phantom graph edges between unrelated entities that merely share an industry word.
+
+Users can query with or without the prefix — `find ai` and `find topic:ai` are equivalent.

package/assets/templates/PAL/README.md

@@ -82,7 +82,7 @@ Persistent storage across sessions:
 - **state/** — Session registry, counts cache, debug logs
 
 ### Tools (`src/tools/`)
-CLI utilities: `tool:opinion` (manage opinions), `tool:reflect` (relationship reflection), `tool:analyze` (learning analysis), `pal cli usage` (token usage tracking), `tool:export` / `tool:import` (state portability).
+CLI utilities: `tool:opinion` (manage opinions), `tool:reflect` (relationship reflection), `tool:analyze` (learning analysis), `pal cli usage` (token usage tracking), `pal cli export` / `pal cli import` (state portability).
 
 ### TELOS (`telos/`)
 Personal context system — mission, goals, projects, beliefs, challenges, strategies, ideas, learnings, mental models, narratives. Managed via the telos skill.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.41.1",
+  "version": "0.42.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "src/",
     "assets/",
+    ".husky/install.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -42,8 +43,7 @@
     "check-write": "biome check --write",
     "knip": "knip-bun",
     "klint": "klint",
-    "jscpd": "jscpd src --noTips --silent",
-    "jscpd:report": "jscpd src --noTips",
+    "jscpd": "jscpd --noTips",
     "lint-staged": "lint-staged",
     "prepare": "bun .husky/install.mjs",
     "install:all": "bun run src/cli/index.ts cli install",
@@ -52,9 +52,7 @@
     "tool:thread": "bun run src/tools/agent/thread.ts",
     "tool:analyze": "bun run src/tools/agent/analyze.ts",
     "tool:wisdom-frame": "bun run src/tools/agent/wisdom-frame.ts",
-    "tool:reflect": "bun run src/tools/relationship-reflect.ts",
-    "tool:export": "bun run src/tools/export.ts",
-    "tool:import": "bun run src/tools/import.ts"
+    "tool:reflect": "bun run src/tools/relationship-reflect.ts"
   },
   "lint-staged": {
     "*.ts": [
@@ -62,9 +60,9 @@
     ]
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.7",
-    "@commitlint/cli": "^20.5.3",
-    "@commitlint/config-conventional": "^20.5.3",
+    "@biomejs/biome": "2.4.15",
+    "@commitlint/cli": "21.0.1",
+    "@commitlint/config-conventional": "21.0.1",
     "@opencode-ai/plugin": "latest",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
@@ -75,15 +73,15 @@
     "husky": "^9.1.7",
     "jscpd": "^4.2.3",
     "knip": "^6.14.1",
-    "lint-staged": "^15.5.2",
+    "lint-staged": "17.0.5",
     "semantic-release": "^25.0.3",
     "typescript": "^5.9.3"
   },
   "dependencies": {
     "@clack/prompts": "^1.4.0",
-    "@konvert7/klint": "^0.2.0",
+    "@konvert7/klint": "0.4.0",
     "adm-zip": "^0.5.17",
-    "marked": "^15.0.12",
+    "marked": "18.0.4",
     "playwright": "^1.60.0"
   }
 }

package/src/cli/index.ts

@@ -186,6 +186,12 @@ async function runCli(command: string | undefined, args: string[]) {
       usage();
       break;
     }
+    case "knowledge": {
+      const { runKnowledge } = await import("./knowledge");
+      const code = await runKnowledge(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "--help":
     case "-h":
     case "help":
@@ -226,6 +232,8 @@ function showHelp() {
     pal cli doctor [--probe-inference]      Check prerequisites and health (--probe fires real inference per route)
     pal cli migrate [--list] [--dry-run]    Run pending data migrations
     pal cli usage                           Summarize token usage and cost
+    pal cli knowledge <sub> [args]          Query & manage the knowledge store
+                                            (search · graph · stats · hubs · find · show · add · ls)
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)