@mnexium/core 0.1.0 → 0.1.1

package/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: publish-npm-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      - name: Upgrade npm for Trusted Publisher
+        run: |
+          npm install -g npm@latest
+          npm --version
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Resolve package metadata
+        id: meta
+        run: |
+          echo "name=$(node -p 'require(\"./package.json\").name')" >> "$GITHUB_OUTPUT"
+          echo "version=$(node -p 'require(\"./package.json\").version')" >> "$GITHUB_OUTPUT"
+
+      - name: Check if version already exists
+        id: check
+        run: |
+          if npm view "${{ steps.meta.outputs.name }}@${{ steps.meta.outputs.version }}" version >/dev/null 2>&1; then
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+            echo "Version already exists on npm; skipping publish."
+          else
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+            echo "Version not found on npm; publishing."
+          fi
+
+      - name: Publish package
+        if: steps.check.outputs.should_publish == 'true'
+        run: npm publish --access public --provenance

package/README.md

@@ -1,37 +1,86 @@
-# CORE
+# 🧠 CORE
 
-CORE is Mnexium's memory engine service: a Postgres-backed HTTP API for storing memories, extracting claims, resolving truth state, and retrieving relevant context for downstream applications.
+CORE is Mnexium's memory engine: a Postgres-backed HTTP service for durable memory, claim extraction, truth-state resolution, and retrieval for LLM applications.
 
-It is designed as an integration-first core service that can run standalone and plug into existing auth, tenancy, and platform controls.
+It is built to run standalone and integrate cleanly into existing platform stacks.
 
-## What CORE does
+## ✨ Why LLM App Teams Use CORE
 
-- Stores subject-scoped memories and supports lifecycle operations (create, update, soft-delete, restore).
-- Extracts structured claims from natural language and persists claim assertions.
-- Maintains slot-based truth state (`slot_state`) to track active winners and retractions.
-- Supports retrieval with vector + lexical fallback and optional LLM-powered query expansion/reranking.
-- Streams memory lifecycle events over SSE for real-time consumers.
+- **Grounded outputs:** retrieve durable user memory instead of relying only on short chat context.
+- **Persistent personalization:** keep preferences, history, and decisions across sessions/channels.
+- **Lower hallucination risk:** combine memory retrieval with claim/slot truth state.
+- **Context-window relief:** recall important memory on demand without re-prompting everything.
+- **Faster shipping:** use a ready memory/truth backend instead of building custom memory infra.
 
-## Why it is powerful
+## 🔩 What CORE Provides
 
-- Better grounding for responses: LLMs can retrieve durable, user-specific memory instead of relying only on short chat context.
-- Lower hallucination risk on known facts: retrieval and claim state give the model a concrete memory substrate to reference.
-- Personalization that persists: preferences, history, and prior decisions survive across sessions and channels.
-- Works beyond context-window limits: important memory is stored and recalled on demand instead of repeatedly reprompted.
-- Faster LLM product development: app teams get a ready memory/truth backend rather than building custom memory pipelines from scratch.
+- Memory lifecycle APIs: create, list, search, update, soft-delete, restore.
+- Memory extraction from text (`/api/v1/memories/extract`) with optional learning writes.
+- Claim APIs with slot-based truth resolution and retraction workflows.
+- Retrieval engine with vector + lexical search and LLM-expanded modes.
+- SSE stream for memory events (`memory.created`, `memory.superseded`, `memory.updated`, `memory.deleted`).
 
-## Intended use
+## 🧱 Core Concepts
 
-CORE is intended to be the memory and truth substrate behind apps, agents, and workflows that need:
+- **Memory:** user-scoped durable facts/context.
+- **Claim:** structured assertion (`predicate`, `object_value`, metadata).
+- **Slot state (`slot_state`):** active winner for a semantic slot.
+- **Supersession:** medium-similarity memories can be marked superseded by newer memories.
 
-- long-lived user memory,
-- auditable claim history,
-- query-time recall,
-- and deterministic APIs backed by Postgres.
+## 🔎 Retrieval Intelligence
 
-## Documentation map
+When LLM retrieval expansion is enabled, search classifies queries into:
 
-- Setup and initialization: [docs/SETUP.md](docs/SETUP.md)
-- Runtime behavior and decision logic: [docs/BEHAVIOR.md](docs/BEHAVIOR.md)
-- HTTP endpoints and contracts: [docs/API.md](docs/API.md)
-- Production hardening checklist: [docs/OPERATIONS.md](docs/OPERATIONS.md)
+- **`broad`**: profile/summary recall (importance + recency weighted).
+- **`direct`**: specific fact lookup with truth/claim-aware boosts.
+- **`indirect`**: advice/planning prompts with expanded query set + rerank.
+
+Fallback behavior is built in:
+
+- missing LLM provider keys -> simple retrieval/extraction mode
+- missing embedding key -> non-vector lexical path still works
+
+## ⚙️ Runtime Modes
+
+`CORE_AI_MODE` supports:
+
+- `auto` (default): `cerebras -> openai -> simple`
+- `cerebras`: requires `CEREBRAS_API` (else falls back to simple)
+- `openai`: requires `OPENAI_API_KEY` (else falls back to simple)
+- `simple`: no LLM client
+
+`USE_RETRIEVAL_EXPAND` controls search-time classify/expand/rerank behavior.
+
+## 🚀 Quick Start
+
+Use the setup guide for the complete runbook, Docker path, and environment reference:
+
+- [Setup and initialization](https://github.com/mnexium/core-mnx/blob/main/docs/SETUP.md)
+
+## 🧪 API Surface
+
+Key route groups:
+
+- health: `GET /health`
+- memories: `/api/v1/memories*`
+- claims/truth: `/api/v1/claims*`
+- events: `GET /api/v1/events/memories`
+
+Full endpoint contracts:
+
+- [HTTP endpoints and contracts](https://github.com/mnexium/core-mnx/blob/main/docs/API.md)
+
+## 🛡️ Production Posture
+
+CORE is integration-first. Auth, tenancy policy, idempotency strategy, and event bus scaling are intentionally externalized so you can fit CORE into your existing platform controls.
+
+Production checklist:
+
+- [Production hardening checklist](https://github.com/mnexium/core-mnx/blob/main/docs/OPERATIONS.md)
+
+## 📚 Documentation Map
+
+- ⚙️ Setup and initialization: [docs/SETUP.md](https://github.com/mnexium/core-mnx/blob/main/docs/SETUP.md)
+- 🧠 Runtime behavior and decision logic: [docs/BEHAVIOR.md](https://github.com/mnexium/core-mnx/blob/main/docs/BEHAVIOR.md)
+- 📘 HTTP endpoints and contracts: [docs/API.md](https://github.com/mnexium/core-mnx/blob/main/docs/API.md)
+- 🛠️ Production hardening checklist: [docs/OPERATIONS.md](https://github.com/mnexium/core-mnx/blob/main/docs/OPERATIONS.md)

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@mnexium/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mnexium/core-mnx"
+  },
+  "homepage": "https://github.com/mnexium/core-mnx",
+  "bugs": {
+    "url": "https://github.com/mnexium/core-mnx/issues"
+  },
   "publishConfig": {
     "access": "public"
   },