@mnemahq/cli 0.1.0

package/LICENSE.md

@@ -0,0 +1,83 @@
+# Mnema Community License
+
+_Version 1.0_
+
+This Community License is based on the "Sustainable Use License" fair-code model.
+It governs the **public core** of Mnema (the `mnema` repository). The enterprise
+modules (`mnema-ee`) are covered by a separate proprietary license and are **not**
+distributed under this license.
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable,
+non-transferable license to use, copy, distribute, make available, and prepare
+derivative works of the software, in each case subject to the limitations and
+conditions below.
+
+## Limitations
+
+**Internal business purposes and personal use.** You may use the software for your
+own internal business purposes or for personal use, and you may make the software
+available to third parties **only** as part of a product or service you provide that
+is not itself the software (or a modified version of it).
+
+You may **not**, without a separate commercial agreement with the licensor:
+
+1. **Host or offer the software as a service** to third parties (commercial hosting,
+   SaaS, or a multi-tenant deployment operated for others).
+2. **Resell, sublicense, or redistribute the software as a product** whose primary
+   value is the software itself.
+3. **Embed the software** into a commercial product offered to third parties where
+   the software provides the core functionality.
+4. Remove or obscure any licensing, copyright, or other notices.
+
+Using the software for **internal tooling, self-hosting for your own team or
+organisation, evaluation, education, or development** is always permitted.
+
+## Trademarks
+
+This license does not grant you any right to use the licensor's trademarks, trade
+names, or logos (including "Mnema"). Forks may use the code; they may not use the name.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can license,
+to make, use, sell, and import the software, limited to the same scope as the
+copyright license above. This patent license terminates if you assert a patent claim
+against anyone alleging the software infringes a patent.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also
+gets a copy of these terms, and you must retain all copyright and licensing notices.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted here.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed, and
+your licenses will automatically terminate. If the licensor provides you notice of a
+violation and you cease the violation within 30 days, your licenses are reinstated.
+
+## No Liability & As-Is
+
+**As far as the law allows, the software comes "as is", without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out of
+these terms or the use or nature of the software, under any kind of legal claim.**
+
+## Definitions
+
+The **licensor** is the entity offering these terms. The **software** is the software
+the licensor makes available under these terms, including any portion of it. **You**
+refers to the individual or entity agreeing to these terms.
+
+---
+
+For commercial hosting, embedding, or reselling rights — or for the enterprise
+(`mnema-ee`) modules — contact the licensor for a commercial agreement.

package/README.md

@@ -0,0 +1,63 @@
+# @mnemahq/cli
+
+Connect a repository to your [Mnema](https://mnema.theboringpeople.in) workspace: install
+Claude Code session capture (real token cost, git, files touched), backfill past sessions, and
+search your workspace — all from the terminal.
+
+## Quick start
+
+```bash
+npm install -g @mnemahq/cli
+mnema init
+```
+
+The package is `@mnemahq/cli`; the command it installs is **`mnema`**. (The unscoped
+name `mnema` is blocked on npm — its typosquat filter rejects it as too close to the
+existing package `mem`.)
+
+You'll be asked for your **workspace id** and a **hook token** (both in *Settings → Developer*), and
+optionally an **API key** for search. `init` installs the capture hook, stores your secrets in the OS
+keychain, and writes a `.mnema/config.json` (safe to commit — it holds no secrets).
+
+Start a Claude Code session and it appears under **Sessions** with its cost.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `mnema init` | Link the repo, install session capture, store secrets |
+| `mnema status` | Connection, hook, API reachability, last session |
+| `mnema sessions` | Recent sessions for this repo (local + server) |
+| `mnema sweep` | Backfill past local sessions (opt-in, no history backfill) |
+| `mnema pull` | Export repo-bound docs into `.mnema/context/**.md` (committed, offline-readable) |
+| `mnema search "q"` | Search your workspace |
+| `mnema doctor` | Diagnose install, hooks, auth, connectivity |
+| `mnema uninstall` | Remove hooks and stored secrets (`--purge` also deletes `.mnema/`) |
+
+## Secrets & privacy
+
+Secrets are stored in the **OS keychain** (macOS Keychain, libsecret on Linux); if none is available
+they fall back to a `0600` file under your config dir. A token is **never** written into the
+committed `.mnema/config.json`. The capture hook sends metadata and file paths only — never file
+contents. See the [privacy details](https://mnema.theboringpeople.in/docs/connect-agent).
+
+`--origin <url>` (or `MNEMA_API_ORIGIN`) points the CLI at a self-hosted instance.
+
+Requires Node 18+ and `git`.
+
+## `.mnema/` repo artifacts
+
+`mnema init` scaffolds a committed `.mnema/` directory and `mnema pull` fills it:
+
+```
+.mnema/
+  config.json     workspace + repo binding (no secrets)
+  NOTABILITY.md   editable prose describing what's worth capturing in this repo
+  context/**.md   workspace docs bound to this repo — readable offline, diff in PRs
+  manifest.json   sync bookkeeping (hashes only)
+```
+
+**Sync is server-is-truth, but your local edits are never silently overwritten.** On
+`mnema pull`: an untouched file is updated from the server; a file you edited while the
+server didn't change is kept as-is; if both changed, the server version is written beside
+yours as `*.remote.md` (gitignored) and the conflict is reported.

package/bin/mnema.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(`\x1b[31mmnema: ${err?.message || err}\x1b[0m`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@mnemahq/cli",
+  "version": "0.1.0",
+  "description": "Mnema CLI — connect a repo to your Mnema workspace: install session capture, sweep past sessions, and search from the terminal.",
+  "type": "module",
+  "bin": {
+    "mnema": "./bin/mnema.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mnema",
+    "cli",
+    "agent",
+    "claude-code",
+    "sessions"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.7"
+  },
+  "scripts": {
+    "build": "node -e \"process.exit(0)\"",
+    "typecheck": "node --check bin/mnema.mjs && node --check src/cli.mjs && node --check src/util.mjs && node --check src/secrets.mjs",
+    "test": "vitest run"
+  }
+}

package/src/artifacts.mjs

@@ -0,0 +1,148 @@
+/**
+ * .mnema/ repo artifacts (PR 5.4).
+ *
+ * `mnema pull` exports the workspace docs bound to this repo into
+ * `.mnema/context/**.md` — committed, human-readable, git-diffable, and readable
+ * by an agent with no network.
+ *
+ * Sync policy: SERVER IS TRUTH, but local edits are NEVER silently clobbered.
+ *   - local file unchanged since last pull  → overwrite with the server version
+ *   - local edited, server unchanged        → keep the local edit (local ahead)
+ *   - both changed                          → CONFLICT: write the server version to
+ *                                             `<file>.remote.md` (gitignored) and keep
+ *                                             the local file; report it
+ * A manifest (`.mnema/manifest.json`, committed — hashes only, no content) records
+ * the server contentHash and the local hash at the last pull to detect all three.
+ */
+
+import { createHash } from 'node:crypto';
+import { join, dirname } from 'node:path';
+import {
+  existsSync, readFileSync, writeFileSync, mkdirSync,
+} from 'node:fs';
+
+const MANIFEST_VERSION = 1;
+
+function sha256(s) { return createHash('sha256').update(s, 'utf8').digest('hex'); }
+
+/** Sanitize a doc path into a safe relative file path under context/ (no traversal). */
+export function targetRelPath(docPath) {
+  const segments = String(docPath || 'untitled')
+    .split('/')
+    .map((seg) => seg.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, ''))
+    .filter((seg) => seg && seg !== '..' && seg !== '.');
+  const rel = segments.join('/') || 'untitled';
+  return `context/${rel}.md`.replace(/\.md\.md$/, '.md');
+}
+
+function mnemaDir(root) { return join(root, '.mnema'); }
+function manifestPath(root) { return join(mnemaDir(root), 'manifest.json'); }
+
+export function readManifest(root) {
+  try { return JSON.parse(readFileSync(manifestPath(root), 'utf8')); }
+  catch { return { version: MANIFEST_VERSION, files: {} }; }
+}
+function writeManifest(root, m) {
+  mkdirSync(mnemaDir(root), { recursive: true });
+  writeFileSync(manifestPath(root), JSON.stringify(m, null, 2) + '\n');
+}
+
+function renderFile(doc) {
+  const header = `<!-- Synced from Mnema · ${doc.path} · local edits are preserved and surfaced as conflicts on \`mnema pull\` -->\n\n`;
+  return header + (doc.markdown || '');
+}
+
+/**
+ * Applies a set of remote docs to .mnema/context, honouring the sync policy.
+ * Returns a summary { written, updated, kept, conflicts, upToDate, orphaned }.
+ */
+export function applyContext(root, docs) {
+  const manifest = readManifest(root);
+  manifest.files = manifest.files || {};
+  const summary = { written: [], updated: [], kept: [], conflicts: [], upToDate: [], orphaned: [] };
+  const seen = new Set();
+
+  for (const doc of docs) {
+    const rel = targetRelPath(doc.path);
+    seen.add(rel);
+    const abs = join(mnemaDir(root), rel);
+    const entry = manifest.files[rel];
+    const content = renderFile(doc);
+    const remoteHash = doc.contentHash;
+
+    if (!existsSync(abs)) {
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, content);
+      manifest.files[rel] = { docId: doc.docId, remoteHash, localHash: sha256(content), pulledAt: new Date().toISOString() };
+      summary.written.push(rel);
+      continue;
+    }
+
+    const localNow = sha256(readFileSync(abs, 'utf8'));
+    const localEdited = !entry || localNow !== entry.localHash;
+    const remoteChanged = !entry || remoteHash !== entry.remoteHash;
+
+    if (!localEdited) {
+      if (remoteChanged) {
+        writeFileSync(abs, content);
+        manifest.files[rel] = { docId: doc.docId, remoteHash, localHash: sha256(content), pulledAt: new Date().toISOString() };
+        summary.updated.push(rel);
+      } else {
+        summary.upToDate.push(rel);
+      }
+    } else if (!remoteChanged) {
+      // Local ahead of an unchanged server — keep the local edit untouched.
+      summary.kept.push(rel);
+    } else {
+      // Both changed — surface the server version beside the local file, keep local.
+      const sidecar = abs.replace(/\.md$/, '.remote.md');
+      mkdirSync(dirname(sidecar), { recursive: true });
+      writeFileSync(sidecar, content);
+      summary.conflicts.push(rel);
+    }
+  }
+
+  // Docs that were pulled before but are no longer returned: leave the file in
+  // place (non-destructive) and just report it.
+  for (const rel of Object.keys(manifest.files)) {
+    if (!seen.has(rel)) summary.orphaned.push(rel);
+  }
+
+  writeManifest(root, manifest);
+  return summary;
+}
+
+/** Scaffold the editable artifacts on init: NOTABILITY.md + .gitignore + context/. */
+export function scaffold(root) {
+  const dir = mnemaDir(root);
+  mkdirSync(join(dir, 'context'), { recursive: true });
+
+  const gitignore = join(dir, '.gitignore');
+  if (!existsSync(gitignore)) {
+    writeFileSync(gitignore, '# Conflict sidecars from `mnema pull` — transient, do not commit\n*.remote.md\n');
+  }
+
+  const keep = join(dir, 'context', '.gitkeep');
+  if (!existsSync(keep)) writeFileSync(keep, '');
+
+  const notability = join(dir, 'NOTABILITY.md');
+  if (!existsSync(notability)) {
+    writeFileSync(notability, `# What's worth remembering in this repo
+
+Edit this file in prose. Mnema consults it when deciding which decisions, gotchas
+and invariants from a coding session are worth capturing as durable knowledge — so
+tune it to your team's taste instead of a numeric threshold.
+
+## Capture
+
+- Non-obvious decisions and *why* an approach was chosen (or rejected)
+- Gotchas that cost real time; invariants that must not be broken
+- Anything a new engineer or agent would need to not repeat a mistake
+
+## Skip
+
+- Routine, self-evident changes; anything already obvious from the diff
+- Secrets, credentials, or customer data
+`);
+  }
+}