Contributions are welcome, especially fixes, clear documentation, useful diagnostics, and focused improvements that preserve Lore’s local-first design.
Before changing code
Read the README, compatibility contract, and support matrix. For tool or hook changes, inspect lib/capabilities/capability-manifest.mjs first; it is the canonical metadata source. Significant changes to memory behavior, retention, or the database should begin with an issue to discuss the approach.
Set up a checkout
git clone <repo-url> ~/dev/lore
cd ~/dev/loreLore is plain ESM with no build step. Use the Node.js and pnpm versions pinned in the root and website package.json manifests for development dependencies and website commands. If you want to run the checkout as a live Copilot extension, preview and then run the development installer:
node scripts/dev-install.mjs --dry-run
node scripts/dev-install.mjsValidate your work
Run the full test suite before opening a pull request:
npm test
npm run test:smokeFor configuration or schema changes, also run:
npm run validate-schemaKeep unit tests focused and fast. Use smoke tests for scripts, temporary homes, and subprocess behavior. Check rendered browser changes in a browser as well as in source.
Run npm run test:reliability for extraction and recall quality, including mandatory recall cases and grouped recall misses. A passing aggregate score does not imply every proposition was recalled. For isolated native adapter checks, use node scripts/verify-cli-hooks.mjs <codex|claude|antigravity> --mock --json; mock mode never launches a host and leaves native recall pending. Actual authenticated certification and a 14-day candidate soak are separate release gates.
Text output limits failure and grouped recall details to 80 entries each and marks omitted or shortened details. Use npm run test:reliability -- --json for the complete evidence.
Style and scope
Use ESM, two-space indentation, double quotes, semicolons, and trailing commas. Prefer Node built-ins and small focused modules. Preserve unrelated work in a dirty checkout, and keep changes scoped to the behavior being fixed.
Documentation changes
Describe user-visible behavior and mark experimental features clearly. When tool metadata or support changes, update lib/capabilities/capability-manifest.mjs and docs/support-matrix.md together. Keep compatibility and release-facing docs in sync with public behavior.
Pull requests
Use a Conventional Commit title such as fix: handle missing session store. Include the tests you ran, relevant screenshots for browser work, and links to related issues. Fill in the repository pull request template. Release-please uses these titles to classify changes.
Privacy while contributing
Never commit ~/.config/lore/lore.db, lore.json, raw session stores, credentials, or generated exports containing private work. Use temporary homes and fixtures for tests. If reporting a problem, share the smallest reproducible details and redact code, paths, and session notes.