@mnemai/memory-server 0.1.1 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to `@mnemai/memory-server` are documented here.
 
+## [0.1.4] - 2026-04-02
+
+### Fixed
+
+- **npm README:** Link to `docs/` and repo files with **absolute GitHub URLs** so they work on [npmjs.com](https://www.npmjs.com/package/@mnemai/memory-server) (the `docs/` tree is not shipped in the package tarball).
+- **package.json:** Add `repository`, `homepage`, and `bugs` for discoverability.
+
+## [0.1.3] - 2026-04-02
+
+### Changed
+
+- **Branding / env:** Prefer **`MNEMAI_MEMORY_*`** environment variables (documented on npm README). Legacy **`TENGU_MEMORY_*`** names remain supported for all memory tuning and embeddings.
+- **Default DB path:** New installs use **`~/.mnemai/memory.db`**. If **`~/.tengu/memory.db`** already exists, it is used until you migrate or set **`MNEMAI_MEMORY_DB`** explicitly.
+
+## [0.1.2] - 2026-04-02
+
+### Fixed
+
+- Include **`LICENSE`** (MIT) in the published tarball via the `files` list so npm consumers get an explicit license file.
+
 ## [0.1.1] - 2026-04-02
 
 ### Fixed

package/README.md

@@ -2,10 +2,12 @@
 
 **Memory 2.0** — MCP server for an **evidence-linked memory graph**: typed nodes, relationships, freshness decay, contradiction hints, and ranked retrieval with explicit provenance fields. **Local-first** (SQLite file on disk).
 
+**Where the docs live:** This page is the npm **README** only. Deeper guides (security, competitive benchmark, RFC, performance, host matrix) are Markdown files in the **[`docs/` folder on GitHub](https://github.com/ashahi10/src/tree/main/docs)** — readable by anyone **when the repository is public**. They are **not** bundled inside the npm tarball.
+
 ## Capabilities
 
 | Area | What you get |
-|------|----------------|
+|------|--------------|
 | Structure | Typed nodes, edges (`supports`, `contradicts`, …), evidence rows |
 | Retrieval | Hybrid **substring + BM25-style token index** + **optional embeddings**; bounded candidates on large graphs |
 | Trust / time | Freshness decay, refresh, spaced **review queue**, confidence rules with evidence |
@@ -26,13 +28,13 @@ MCP config (set an absolute DB path):
     "mnemai-memory": {
       "command": "npx",
       "args": ["--yes", "@mnemai/memory-server"],
-      "env": { "TENGU_MEMORY_DB": "/absolute/path/to/memory.db" }
+      "env": { "MNEMAI_MEMORY_DB": "/absolute/path/to/memory.db" }
     }
   }
 }
 ```
 
-Publishing and version bumps: see repo [RELEASING.md](../../RELEASING.md). `prepublishOnly` runs **`pnpm run verify:ship`**.
+Publishing and version bumps: see **[RELEASING.md](https://github.com/ashahi10/src/blob/main/RELEASING.md)**. `prepublishOnly` runs **`pnpm run verify:ship`**.
 
 ## What `verify:ship` checks
 
@@ -43,7 +45,7 @@ Publishing and version bumps: see repo [RELEASING.md](../../RELEASING.md). `prep
 
 **Scope:** Proves the **reference SDK wire path** on CI’s OS (Linux). Hosts can still differ (timeouts, stderr). Not a guarantee for every proprietary MCP client.
 
-Repo CI also builds the workspace, typechecks, verifies **mission** + **verification** servers, **npm pack** sanity, and the **platform demo** (see root [README.md](../../README.md)).
+Repo CI also builds the workspace, typechecks, verifies **mission** + **verification** servers, **npm pack** sanity, and the **platform demo** (see root **[README.md](https://github.com/ashahi10/src/blob/main/README.md)**).
 
 ## Requirements
 
@@ -62,19 +64,21 @@ node packages/memory-server/dist/index.js
 
 ## Environment variables
 
+Use the **`MNEMAI_MEMORY_*`** names below. The same settings also accept legacy **`TENGU_MEMORY_*`** names (for older configs).
+
 | Variable | Purpose |
 |----------|---------|
-| `TENGU_MEMORY_DB` | Path to the SQLite file (default: `~/.tengu/memory.db`) |
-| `TENGU_MEMORY_SYNC_WRITES=1` | Flush to disk immediately after writes (stronger durability, slower) |
-| `TENGU_MEMORY_MATCH_LEXICAL` | Weight for substring overlap in hybrid `matchScore` (default `0.35`; renormalized with index/semantic) |
-| `TENGU_MEMORY_MATCH_INDEX` | Weight for BM25-style token index (default `0.45`) |
-| `TENGU_MEMORY_MATCH_SEMANTIC` | Weight for embedding cosine channel when enabled (default `0.2`) |
-| `TENGU_MEMORY_EMBED_URL` | OpenAI-compatible **POST** embeddings endpoint |
-| `TENGU_MEMORY_EMBED_KEY` | Bearer token for that endpoint |
-| `TENGU_MEMORY_EMBED_MODEL` | Embedding model id (default `text-embedding-3-small`) |
-| `TENGU_MEMORY_QUERY_FULL_SCAN_MAX_NODES` | Graphs larger than this use **index-bounded candidates** + recent seed (default `1600`; `0` = always use smart path when the index matches) |
-| `TENGU_MEMORY_QUERY_INDEX_CANDIDATE_CAP` | Floor for max BM25-hit ids per query; effective cap is `max(this, limit×25)` (default `600`) |
-| `TENGU_MEMORY_QUERY_RECENT_SEED` | Union this many most recently updated nodes (after filters) (default `200`) |
+| `MNEMAI_MEMORY_DB` | Path to the SQLite file. If unset: uses existing `~/.tengu/memory.db` when present, otherwise creates **`~/.mnemai/memory.db`**. |
+| `MNEMAI_MEMORY_SYNC_WRITES=1` | Flush to disk immediately after writes (stronger durability, slower). Legacy: `TENGU_MEMORY_SYNC_WRITES=1`. |
+| `MNEMAI_MEMORY_MATCH_LEXICAL` | Weight for substring overlap in hybrid `matchScore` (default `0.35`; renormalized with index/semantic). Legacy `TENGU_*` alias. |
+| `MNEMAI_MEMORY_MATCH_INDEX` | Weight for BM25-style token index (default `0.45`). Legacy alias. |
+| `MNEMAI_MEMORY_MATCH_SEMANTIC` | Weight for embedding cosine channel when enabled (default `0.2`). Legacy alias. |
+| `MNEMAI_MEMORY_EMBED_URL` | OpenAI-compatible **POST** embeddings endpoint. Legacy alias. |
+| `MNEMAI_MEMORY_EMBED_KEY` | Bearer token for that endpoint. Legacy alias. |
+| `MNEMAI_MEMORY_EMBED_MODEL` | Embedding model id (default `text-embedding-3-small`). Legacy alias. |
+| `MNEMAI_MEMORY_QUERY_FULL_SCAN_MAX_NODES` | Graphs larger than this use **index-bounded candidates** + recent seed (default `1600`; `0` = always use smart path when the index matches). Legacy alias. |
+| `MNEMAI_MEMORY_QUERY_INDEX_CANDIDATE_CAP` | Floor for max BM25-hit ids per query; effective cap is `max(this, limit×25)` (default `600`). Legacy alias. |
+| `MNEMAI_MEMORY_QUERY_RECENT_SEED` | Union this many most recently updated nodes (after filters) (default `200`). Legacy alias. |
 
 ## MCP config (clone / local `node`)
 
@@ -84,7 +88,7 @@ node packages/memory-server/dist/index.js
     "mnemai-memory": {
       "command": "node",
       "args": ["/absolute/path/to/repo/packages/memory-server/dist/index.js"],
-      "env": { "TENGU_MEMORY_DB": "/absolute/path/to/my-memory.db" }
+      "env": { "MNEMAI_MEMORY_DB": "/absolute/path/to/my-memory.db" }
     }
   }
 }
@@ -103,7 +107,7 @@ Use **absolute paths** — hosts often use a cwd that is not your repo.
 | `memory.refresh` | Reaffirm / boost freshness; optional `reaffirmationNote` |
 | `memory.list_review_queue` | Spaced verification queue |
 | `memory.verify_node` | Confirm a memory still holds |
-| `memory.embed_node` | Store embedding (requires `TENGU_MEMORY_EMBED_*`) |
+| `memory.embed_node` | Store embedding (requires `MNEMAI_MEMORY_EMBED_*` or legacy `TENGU_MEMORY_EMBED_*`) |
 | `memory.stats` | Aggregate stats (+ index / embedding counts) |
 
 ## Resources
@@ -115,17 +119,17 @@ Use **absolute paths** — hosts often use a cwd that is not your repo.
 
 ## Security, performance, limits
 
-- [Security & privacy](../../docs/Memory-2.0-Security-Privacy.md)
-- [Performance (test SLOs)](../../docs/Memory-2.0-Performance.md)
-- [Host matrix](../../docs/Memory-2.0-Host-Matrix.md)
+- [Security & privacy](https://github.com/ashahi10/src/blob/main/docs/Memory-2.0-Security-Privacy.md)
+- [Performance (test SLOs)](https://github.com/ashahi10/src/blob/main/docs/Memory-2.0-Performance.md)
+- [Host matrix](https://github.com/ashahi10/src/blob/main/docs/Memory-2.0-Host-Matrix.md)
 
 **Limits (honest):** **sql.js** build has **no FTS5**; lexical search uses **`node_search_tokens`** + BM25-style scoring plus substring match. **Embeddings** are optional and require your own API. Large graphs use **bounded retrieval** (see env vars above). These tradeoffs favor **portable, predictable** local operation over mimicking a hosted search product.
 
 ## Related docs
 
-- [RFC: Memory 2.0](../../docs/RFC-Memory-2.0.md)
-- [Runtime compatibility](../../docs/Memory-2.0-Runtime-Compatibility.md)
-- [Competitive benchmark](../../docs/Memory-2.0-Competitive-Benchmark.md)
+- [RFC: Memory 2.0](https://github.com/ashahi10/src/blob/main/docs/RFC-Memory-2.0.md)
+- [Runtime compatibility](https://github.com/ashahi10/src/blob/main/docs/Memory-2.0-Runtime-Compatibility.md)
+- [Competitive benchmark](https://github.com/ashahi10/src/blob/main/docs/Memory-2.0-Competitive-Benchmark.md)
 
 ## License
 

package/dist/index.js

@@ -37,9 +37,7 @@ import { v4 as uuidv4 } from "uuid";
 
 // src/graph/store.ts
 import initSqlJs from "sql.js";
-import { homedir } from "os";
-import { join } from "path";
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
+import { readFileSync, writeFileSync, existsSync as existsSync2 } from "fs";
 
 // src/retrieval/tokenize.ts
 var STOPWORDS = /* @__PURE__ */ new Set([
@@ -206,23 +204,39 @@ function searchIndexTableExists(database) {
   return ok;
 }
 
+// src/envMemory.ts
+import { existsSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+function preferMnemaiEnv(mnemaiName, tenguName) {
+  const a = process.env[mnemaiName]?.trim();
+  if (a) return a;
+  const b = process.env[tenguName]?.trim();
+  return b || void 0;
+}
+function getMemoryDbPath() {
+  const explicit = preferMnemaiEnv("MNEMAI_MEMORY_DB", "TENGU_MEMORY_DB");
+  if (explicit) return explicit;
+  const legacyFile = join(homedir(), ".tengu", "memory.db");
+  if (existsSync(legacyFile)) return legacyFile;
+  const dir = join(homedir(), ".mnemai");
+  mkdirSync(dir, { recursive: true });
+  return join(dir, "memory.db");
+}
+function isMemorySyncWrites() {
+  return process.env.MNEMAI_MEMORY_SYNC_WRITES === "1" || process.env.TENGU_MEMORY_SYNC_WRITES === "1";
+}
+
 // src/graph/store.ts
 var db = null;
 var dbPath = null;
 var saveTimer = null;
-var SYNC_WRITES = process.env.TENGU_MEMORY_SYNC_WRITES === "1";
-function getDbPath() {
-  const envPath = process.env.TENGU_MEMORY_DB;
-  if (envPath) return envPath;
-  const dir = join(homedir(), ".tengu");
-  mkdirSync(dir, { recursive: true });
-  return join(dir, "memory.db");
-}
+var SYNC_WRITES = isMemorySyncWrites();
 async function initDb() {
   if (db) return db;
   const SQL = await initSqlJs();
-  dbPath = getDbPath();
-  if (existsSync(dbPath)) {
+  dbPath = getMemoryDbPath();
+  if (existsSync2(dbPath)) {
     const buffer = readFileSync(dbPath);
     db = new SQL.Database(buffer);
   } else {
@@ -779,17 +793,25 @@ var INTENT_WEIGHTS = {
   incident_triage: { relevance: 0.35, freshness: 0.35, evidence: 0.2, salience: 0.1 },
   preference_personalization: { relevance: 0.35, freshness: 0.2, evidence: 0.15, salience: 0.3 }
 };
-function parseEnvWeight(name, fallback) {
-  const v = process.env[name];
-  if (v == null || v === "") return fallback;
-  const n = Number(v);
+function parseEnvWeightRaw(raw, fallback) {
+  if (raw == null || raw === "") return fallback;
+  const n = Number(raw);
   if (!Number.isFinite(n) || n < 0) return fallback;
   return n;
 }
 function matchBlendWeights(useSemantic) {
-  let lex = parseEnvWeight("TENGU_MEMORY_MATCH_LEXICAL", 0.35);
-  let idx = parseEnvWeight("TENGU_MEMORY_MATCH_INDEX", 0.45);
-  let sem = parseEnvWeight("TENGU_MEMORY_MATCH_SEMANTIC", 0.2);
+  let lex = parseEnvWeightRaw(
+    preferMnemaiEnv("MNEMAI_MEMORY_MATCH_LEXICAL", "TENGU_MEMORY_MATCH_LEXICAL"),
+    0.35
+  );
+  let idx = parseEnvWeightRaw(
+    preferMnemaiEnv("MNEMAI_MEMORY_MATCH_INDEX", "TENGU_MEMORY_MATCH_INDEX"),
+    0.45
+  );
+  let sem = parseEnvWeightRaw(
+    preferMnemaiEnv("MNEMAI_MEMORY_MATCH_SEMANTIC", "TENGU_MEMORY_MATCH_SEMANTIC"),
+    0.2
+  );
   if (!useSemantic) {
     const total = lex + idx;
     if (total <= 0) return { lex: 0.55, idx: 0.45, sem: 0 };
@@ -948,15 +970,17 @@ function computeConflict(node, edges, nodeById) {
 // src/retrieval/embedding.ts
 var DEFAULT_MODEL = "text-embedding-3-small";
 function isEmbeddingsConfigured() {
-  return Boolean(process.env.TENGU_MEMORY_EMBED_URL?.trim() && process.env.TENGU_MEMORY_EMBED_KEY?.trim());
+  const url = preferMnemaiEnv("MNEMAI_MEMORY_EMBED_URL", "TENGU_MEMORY_EMBED_URL");
+  const key = preferMnemaiEnv("MNEMAI_MEMORY_EMBED_KEY", "TENGU_MEMORY_EMBED_KEY");
+  return Boolean(url && key);
 }
 function getEmbeddingModel() {
-  return process.env.TENGU_MEMORY_EMBED_MODEL?.trim() || DEFAULT_MODEL;
+  return preferMnemaiEnv("MNEMAI_MEMORY_EMBED_MODEL", "TENGU_MEMORY_EMBED_MODEL") || DEFAULT_MODEL;
 }
 async function embedText(text) {
   if (!isEmbeddingsConfigured()) return null;
-  const url = process.env.TENGU_MEMORY_EMBED_URL.trim();
-  const key = process.env.TENGU_MEMORY_EMBED_KEY.trim();
+  const url = preferMnemaiEnv("MNEMAI_MEMORY_EMBED_URL", "TENGU_MEMORY_EMBED_URL");
+  const key = preferMnemaiEnv("MNEMAI_MEMORY_EMBED_KEY", "TENGU_MEMORY_EMBED_KEY");
   const model = getEmbeddingModel();
   const body = JSON.stringify({ model, input: text.slice(0, 8e3) });
   const res = await fetch(url, {
@@ -1042,9 +1066,27 @@ function parseNonNegativeInt(raw, fallback) {
 }
 function parseQueryRetrievalBudget() {
   return {
-    fullScanMaxNodes: parseNonNegativeInt(process.env.TENGU_MEMORY_QUERY_FULL_SCAN_MAX_NODES, 1600),
-    indexCandidateCapFloor: Math.max(1, parseNonNegativeInt(process.env.TENGU_MEMORY_QUERY_INDEX_CANDIDATE_CAP, 600)),
-    recentSeedSize: parseNonNegativeInt(process.env.TENGU_MEMORY_QUERY_RECENT_SEED, 200)
+    fullScanMaxNodes: parseNonNegativeInt(
+      preferMnemaiEnv(
+        "MNEMAI_MEMORY_QUERY_FULL_SCAN_MAX_NODES",
+        "TENGU_MEMORY_QUERY_FULL_SCAN_MAX_NODES"
+      ),
+      1600
+    ),
+    indexCandidateCapFloor: Math.max(
+      1,
+      parseNonNegativeInt(
+        preferMnemaiEnv(
+          "MNEMAI_MEMORY_QUERY_INDEX_CANDIDATE_CAP",
+          "TENGU_MEMORY_QUERY_INDEX_CANDIDATE_CAP"
+        ),
+        600
+      )
+    ),
+    recentSeedSize: parseNonNegativeInt(
+      preferMnemaiEnv("MNEMAI_MEMORY_QUERY_RECENT_SEED", "TENGU_MEMORY_QUERY_RECENT_SEED"),
+      200
+    )
   };
 }
 function effectiveIndexHitCap(limit, capFloor) {
@@ -1183,10 +1225,10 @@ var queryMemorySchema = z2.object({
     "Include BM25-style portable token index in hybrid rank (default true when index exists)."
   ),
   useSemantic: z2.boolean().optional().describe(
-    "Allow query-time embedding call when TENGU_MEMORY_EMBED_* is configured (default true)."
+    "Allow query-time embedding call when MNEMAI_MEMORY_EMBED_* (or TENGU_MEMORY_EMBED_*) is configured (default true)."
   ),
   fullScan: z2.boolean().optional().describe(
-    "Load the entire filtered graph for ranking (slower, strongest recall). Default uses index-bounded candidates when the graph is larger than TENGU_MEMORY_QUERY_FULL_SCAN_MAX_NODES."
+    "Load the entire filtered graph for ranking (slower, strongest recall). Default uses index-bounded candidates when the graph is larger than MNEMAI_MEMORY_QUERY_FULL_SCAN_MAX_NODES (or TENGU_* alias)."
   )
 });
 async function handleQueryMemory(args) {
@@ -1564,7 +1606,7 @@ async function handleEmbedNode(args) {
           type: "text",
           text: JSON.stringify({
             error: "embeddings_not_configured",
-            hint: "Set TENGU_MEMORY_EMBED_URL (OpenAI-compatible embeddings endpoint), TENGU_MEMORY_EMBED_KEY, and optionally TENGU_MEMORY_EMBED_MODEL."
+            hint: "Set MNEMAI_MEMORY_EMBED_URL (OpenAI-compatible embeddings endpoint), MNEMAI_MEMORY_EMBED_KEY, and optionally MNEMAI_MEMORY_EMBED_MODEL (legacy TENGU_MEMORY_EMBED_* still work)."
           }, null, 2)
         }
       ],
@@ -1622,7 +1664,7 @@ ${node.tags.join(" ")}`.slice(0, 8e3);
 // src/index.ts
 var server = new McpServer({
   name: "mnemai-memory",
-  version: "0.1.1"
+  version: "0.1.4"
 });
 server.tool(
   "memory.create_node",
@@ -1674,7 +1716,7 @@ server.tool(
 );
 server.tool(
   "memory.embed_node",
-  "Store an embedding vector for a node (requires TENGU_MEMORY_EMBED_URL + TENGU_MEMORY_EMBED_KEY); enables semantic channel in memory.query",
+  "Store an embedding vector for a node (requires MNEMAI_MEMORY_EMBED_URL + MNEMAI_MEMORY_EMBED_KEY, or legacy TENGU_* names); enables semantic channel in memory.query",
   embedNodeSchema.shape,
   async (args) => handleEmbedNode(args)
 );
@@ -1745,7 +1787,7 @@ Usage: mnemai-memory
   Starts the Model Context Protocol server on stdin/stdout (no HTTP port).
 
 Docs: https://www.npmjs.com/package/@mnemai/memory-server
-Environment: TENGU_MEMORY_DB (SQLite path), TENGU_MEMORY_EMBED_* (optional embeddings).
+Environment: MNEMAI_MEMORY_DB (SQLite path; legacy TENGU_MEMORY_DB supported), MNEMAI_MEMORY_EMBED_* (optional embeddings; TENGU_* aliases).
 `);
     process.exit(0);
   }

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@mnemai/memory-server",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "MCP server providing evidence-linked memory graph with typed nodes, freshness decay, and contradiction handling",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashahi10/src.git",
+    "directory": "packages/memory-server"
+  },
+  "homepage": "https://github.com/ashahi10/src/tree/main/packages/memory-server#readme",
+  "bugs": {
+    "url": "https://github.com/ashahi10/src/issues"
+  },
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -12,7 +21,8 @@
     "dist",
     "bin",
     "CHANGELOG.md",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"