@fortemi/core 2026.5.2 → 2026.5.4

package/README.md

@@ -2,9 +2,9 @@
 
 # @fortemi/core
 
-**Headless browser knowledge-management core powered by PGlite, typed repositories, and agent tool helpers**
+**Headless browser knowledge-management core powered by PGlite, typed repositories, semantic retrieval, and agent tool helpers**
 
-Local PostgreSQL-compatible storage, migrations, note/search repositories, capability orchestration, Knowledge Shards, and bridge-ready tool metadata for browser applications.
+Build local-first knowledge apps with PostgreSQL-compatible storage in the browser, production-ready repositories, search primitives, Knowledge Shard portability, optional local AI wiring, and bridge-ready tool metadata.
 
 ```bash
 pnpm add @fortemi/core
@@ -16,7 +16,7 @@ pnpm add @fortemi/core
 [![Node Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
 
-[**Install**](#installation) · [**Quick Start**](#quick-start) · [**Surface**](#what-you-get) · [**Tools**](#tool-surface) · [**Docs**](#documentation) · [**License**](#license)
+[**Install**](#installation) · [**Why Fortemi**](#why-fortemi-core) · [**Quick Start**](#quick-start) · [**Surface**](#what-you-get) · [**Tools**](#tool-surface) · [**Docs**](#documentation) · [**License**](#license)
 
 </div>
 
@@ -24,9 +24,36 @@ pnpm add @fortemi/core
 
 ## What @fortemi/core Is
 
-`@fortemi/core` is the headless Fortemi runtime for browser applications. It provides a PGlite-backed archive, repository classes, migrations, eventing, capability management, Knowledge Shard import/export, and tool helpers that can be called from UI code or bridge adapters.
+`@fortemi/core` is the headless Fortemi runtime for browser applications. It gives your app a durable local archive backed by PGlite, typed repository classes, migrations, eventing, capability management, Knowledge Shard import/export, and tool helpers that can be called from UI code or bridge adapters.
 
-Use `@fortemi/core` directly when you are building your own UI, integrating Fortemi into a non-React host, or wiring agent/tool calls against an existing browser database context.
+Use it when you want the browser to own the user's working knowledge: notes, links, tags, collections, SKOS concepts, attachments, search history, revisions, generated metadata, and portable exports. No application server is required for the core archive path, and the same package can power React, non-React, extension, or embedded host integrations.
+
+## Why Fortemi Core
+
+Most browser note and knowledge apps choose between a thin IndexedDB wrapper, a hosted database, or a custom sync protocol. Fortemi starts from a different premise: the browser can run a real PostgreSQL-compatible archive locally, then expose that archive through stable typed APIs and agent-readable tools.
+
+| Need | What Fortemi provides |
+|---|---|
+| Local-first persistence | PGlite storage through OPFS, IndexedDB, or memory modes |
+| Queryable knowledge | SQL-backed repositories for notes, links, tags, collections, SKOS concepts, jobs, and search |
+| Retrieval quality | Full-text search, pgvector-backed semantic search, hybrid ranking, snippets, facets, and filters |
+| AI-ready workflows | Optional embeddings, local LLM capability discovery, job provenance, and fallback routing |
+| Portable archives | Knowledge Shard tar.gz import/export with checksums and JSON format parity |
+| Agent integration | Manifest-backed tools and direct helper functions for bridge adapters and automation |
+| UI freedom | A headless package you can use from React, another framework, a browser extension, or a custom host |
+
+### What You Can Build
+
+- Local-first notebooks, research workspaces, and personal knowledge bases
+- Browser-only semantic search over user-owned notes and imported knowledge
+- AI memory layers for agents that need structured retrieval, provenance, and portable state
+- Web apps that can run from static hosting while still offering durable local storage
+- Import/export pipelines using Knowledge Shards instead of app-specific backup formats
+- Custom React, Svelte, Vue, extension, or embedded UIs on top of the same archive model
+
+### Architecture at a Glance
+
+`ArchiveManager` opens a PGlite database, applies migrations, and scopes storage by archive name. Repository classes provide the canonical data-access layer. `TypedEventBus` keeps UI and background jobs in sync. Capability services track optional AI/runtime features. Tool helpers expose the same data model to bridges, local automations, and agent hosts.
 
 ## Installation
 
@@ -80,16 +107,22 @@ await registerServiceWorker()
 | Surface | Description |
 |---|---|
 | PGlite archive | `opfs`, `idb`, and `memory` persistence modes with migrations on open |
-| Repositories | Notes, search, tags, collections, links, SKOS concepts, and attachments |
+| Repositories | Notes, search, tags, collections, links, SKOS concepts, attachments, embedding sets, graph helpers, jobs, and provenance |
 | Event bus | Typed subscriptions for note, job, archive, and capability events |
 | Capability system | Embeddings, local LLM, GPU detection, local-provider discovery, fallback routing |
 | Job queue | Server-compatible background workflow for revisions, titles, embeddings, concepts, and links |
 | Knowledge Shards | Tar.gz import/export with checksums and JSON format parity |
 | Service-worker helpers | Route registration primitives for standalone browser integration |
 
+## Search and Knowledge Model
+
+Fortemi's archive is more than note CRUD. The schema includes note bodies, generated titles, revision history, tags, collections, inter-note links, SKOS concept schemes, attachments, job provenance, and query history. Search can combine PostgreSQL full-text ranking with pgvector embeddings, then fuse scores for hybrid results.
+
+That gives product teams a foundation for features users already expect from serious knowledge software: fast recall, related-note discovery, semantic retrieval, explainable provenance, import/export, and structured taxonomy support.
+
 ## Tool Surface
 
-`FortemiToolManifest` registers 10 bridge-visible Mnemos tools:
+`FortemiToolManifest` registers 10 bridge-visible Fortemi tools:
 
 `capture_knowledge`, `manage_note`, `search`, `get_note`, `list_notes`, `manage_tags`, `manage_collections`, `manage_links`, `manage_archive`, `manage_capabilities`.
 
@@ -98,9 +131,11 @@ The package also exports 11 direct helper functions from `@fortemi/core`, includ
 ```ts
 import { fortemiManifest } from '@fortemi/core'
 
-const capabilities = fortemiManifest.toPlinyCapabilities()
+const capabilities = fortemiManifest.toBridgeCapabilities()
 ```
 
+Use the manifest when a host needs to advertise Fortemi operations to an agent runtime. Use the direct helper functions when your own code needs the same validated operations without going through a bridge layer.
+
 ## Browser Storage
 
 | Mode | Storage | Best for |
@@ -109,6 +144,8 @@ const capabilities = fortemiManifest.toPlinyCapabilities()
 | `idb` | IndexedDB-backed PGlite data directory | Firefox and broad compatibility |
 | `memory` | In-memory database | Tests, demos, restricted browser contexts |
 
+Data stays in the selected browser storage mode unless your application explicitly exports it, imports it, or wires external providers. Optional AI capabilities are opt-in and can be routed to local WASM, local provider servers, or host-provided integrations depending on your product requirements.
+
 ## React Bindings
 
 For React applications, install `@fortemi/react`. It wraps `@fortemi/core` with `FortemiProvider`, context access, and 21 hooks.