mneva-connect 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# mneva-connect
+
+Connect your coding agent to its hosted **Mneva** brain — persistent memory,
+belief revision, and instinct, over MCP.
+
+Every AI coding tool starts cold: it re-reads your codebase, re-asks what you
+told it last week, repeats the mistake you already corrected. Mneva is the
+mind underneath them — it remembers, it revises, and it carries across every
+session and every tool you use.
+
+## Setup
+
+1. Get an API key at [mneva.dev/signup](https://mneva.dev/signup).
+2. Add this to your coding tool's `.mcp.json` (Claude Code, Cursor, or any
+   MCP client):
+
+   ```json
+   {
+     "mcpServers": {
+       "mneva": {
+         "command": "npx",
+         "args": ["-y", "mneva-connect"],
+         "env": { "MNEVA_KEY": "mnv_your_key_here" }
+       }
+     }
+   }
+   ```
+
+3. Restart your coding tool.
+
+## What your agent gets
+
+| Tool | What it does |
+|------|--------------|
+| `remember` | Record a decision, a fix, a fact — kept across sessions |
+| `recall` | Semantic recall of past memories — finds them by meaning |
+| `believe` | Assert something held true about the project |
+| `revise` | Correct a belief — the old one is superseded for good |
+| `flag` | Mark code as fragile or dangerous |
+| `assess` | Gut-check before working — clear, caution, or danger |
+
+## Environment
+
+- `MNEVA_KEY` *(required)* — your tenant API key
+- `MNEVA_API` *(optional)* — engine base URL, defaults to the hosted service
+
+MIT licensed.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "mneva-connect",
+  "version": "0.1.0",
+  "description": "Connect your coding agent to its hosted Mneva brain — persistent memory, belief revision, and instinct over MCP.",
+  "type": "module",
+  "bin": {
+    "mneva-connect": "./src/index.js"
+  },
+  "scripts": {
+    "prove": "node src/prove.js"
+  },
+  "files": ["src"],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["mcp", "ai", "memory", "agent", "mneva", "claude", "cursor"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  }
+}

package/src/index.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * mneva-connect — connect a coding agent to its hosted Mneva brain.
+ *
+ * This is the package the Mneva signup page tells you to install. It is a
+ * thin MCP stdio server: every tool call is forwarded to your hosted Mneva
+ * brain over HTTPS, authenticated with your MNEVA_KEY. No local database,
+ * no embeddings here — the hosted engine does all of it. Your agent just
+ * sees six tools and a memory that persists everywhere you code.
+ *
+ * Add to your coding tool's .mcp.json:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "mneva": {
+ *         "command": "npx",
+ *         "args": ["-y", "mneva-connect"],
+ *         "env": { "MNEVA_KEY": "mnv_your_key_here" }
+ *       }
+ *     }
+ *   }
+ *
+ * Env:
+ *   MNEVA_KEY   (required) — your tenant API key from the Mneva dashboard
+ *   MNEVA_API   (optional) — engine base URL, defaults to the hosted service
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+// Defaults to the hosted Mneva service. Override MNEVA_API only for
+// self-hosting or local development against your own engine.
+const API = (process.env.MNEVA_API || 'https://mneva.dev').replace(/\/$/, '');
+const KEY = process.env.MNEVA_KEY;
+
+if (!KEY) {
+  console.error(
+    '[mneva] MNEVA_KEY is not set. Add your API key to the mneva server\'s\n' +
+      '        env block in .mcp.json. Get a key at https://mneva.dev/signup',
+  );
+  process.exit(1);
+}
+
+const json = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
+const fail = (msg) => ({ content: [{ type: 'text', text: `error: ${msg}` }], isError: true });
+
+/** Forward one tool call to the hosted brain. */
+async function call(path, body) {
+  let res;
+  try {
+    res = await fetch(`${API}/v1/${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-mneva-key': KEY },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(20000),
+    });
+  } catch (err) {
+    return fail(`could not reach your Mneva brain (${err.message})`);
+  }
+  if (res.status === 401) return fail('your MNEVA_KEY is invalid — check it in the Mneva dashboard');
+  let data;
+  try {
+    data = await res.json();
+  } catch {
+    return fail(`unexpected response from the Mneva engine (HTTP ${res.status})`);
+  }
+  if (!res.ok) return fail(data.error || `Mneva engine error (HTTP ${res.status})`);
+  return json(data);
+}
+
+const server = new McpServer({ name: 'mneva', version: '0.1.0' });
+
+server.registerTool(
+  'remember',
+  {
+    description:
+      'Record something that happened in this project — a decision, a fix, a fact. Your hosted Mneva brain keeps it across every session and every tool.',
+    inputSchema: { text: z.string().describe('What to remember.') },
+  },
+  ({ text }) => call('remember', { text }),
+);
+
+server.registerTool(
+  'recall',
+  {
+    description:
+      'Recall past memories related to a query — semantic, so it finds relevant memories even with no shared words. You do not start cold.',
+    inputSchema: { query: z.string().describe('What to recall about.') },
+  },
+  ({ query }) => call('recall', { query }),
+);
+
+server.registerTool(
+  'believe',
+  {
+    description: 'Assert a belief — something held true about this project (a convention, a constraint).',
+    inputSchema: {
+      text: z.string().describe('The belief to hold.'),
+      confidence: z.number().min(0).max(1).optional(),
+    },
+  },
+  ({ text, confidence }) => call('believe', { text, confidence }),
+);
+
+server.registerTool(
+  'revise',
+  {
+    description:
+      'Revise a belief. The old one is superseded and will never resurface — this is how a corrected mistake stays corrected.',
+    inputSchema: {
+      belief_id: z.number().int().describe('Id of the belief to revise.'),
+      new_text: z.string().describe('The corrected belief.'),
+      confidence: z.number().min(0).max(1).optional(),
+    },
+  },
+  ({ belief_id, new_text, confidence }) => call('revise', { belief_id, new_text, confidence }),
+);
+
+server.registerTool(
+  'flag',
+  {
+    description:
+      'Flag something as dangerous or fragile. Mneva remembers the danger and will warn about it later.',
+    inputSchema: {
+      text: z.string().describe('What is dangerous, and why.'),
+      caution: z.number().min(0).max(1).optional(),
+    },
+  },
+  ({ text, caution }) => call('flag', { text, caution }),
+);
+
+server.registerTool(
+  'assess',
+  {
+    description:
+      'Gut-check a topic before working on it. Returns clear, caution, or danger with the reason — the partner\'s instinct.',
+    inputSchema: { topic: z.string().describe('What you are about to work on.') },
+  },
+  ({ topic }) => call('assess', { topic }),
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`[mneva] connected to your hosted brain at ${API}`);

package/src/prove.js

@@ -0,0 +1,115 @@
+/**
+ * Proof — mneva-connect against the live hosted engine.
+ *
+ * 1. Provision a fresh tenant via the engine admin endpoint.
+ * 2. Spawn mneva-connect as an MCP server with that tenant's key — exactly
+ *    how Cursor / Claude Code would spawn it from .mcp.json.
+ * 3. Call tools through the connector and confirm they reach the hosted
+ *    brain: remember -> recall, flag -> assess, and an invalid key fails loud.
+ *
+ * If this passes, the signup page's .mcp.json snippet is true: install
+ * mneva-connect with your key and your agent is talking to its brain.
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONNECT = join(__dirname, 'index.js');
+const ENGINE = process.env.MNEVA_API || 'http://localhost:8787';
+const ADMIN = process.env.MNEVA_ADMIN_SECRET || 'dev-admin-secret';
+
+let pass = 0;
+let fail = 0;
+const check = (label, cond, detail = '') => {
+  if (cond) { pass++; console.log(`  PASS  ${label}`); }
+  else { fail++; console.log(`  FAIL  ${label}  ${detail}`); }
+};
+
+console.log('\nmneva-connect PROOF (against the live engine)');
+console.log('==============================================\n');
+
+// 1. Provision a fresh tenant.
+let key;
+try {
+  const res = await fetch(`${ENGINE}/admin/tenant`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-mneva-admin': ADMIN },
+    body: JSON.stringify({ name: 'connect-proof' }),
+  });
+  const t = await res.json();
+  key = t.key;
+  check('provisioned a fresh tenant brain', !!key, JSON.stringify(t));
+} catch (err) {
+  console.log(`  FAIL  engine unreachable at ${ENGINE} — start it first (${err.message})`);
+  process.exit(1);
+}
+
+/** Spawn mneva-connect as an MCP server with a given key. */
+async function connector(apiKey) {
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [CONNECT],
+    env: { ...process.env, MNEVA_KEY: apiKey, MNEVA_API: ENGINE },
+  });
+  const client = new Client({ name: 'connect-proof', version: '0.1.0' });
+  await client.connect(transport);
+  return {
+    client,
+    async call(tool, args) {
+      const r = await client.callTool({ name: tool, arguments: args });
+      const t = r.content?.[0]?.text ?? '';
+      try { return { data: JSON.parse(t), isError: !!r.isError }; }
+      catch { return { data: t, isError: !!r.isError }; }
+    },
+    end: () => client.close(),
+  };
+}
+
+// 2. A real session through the connector.
+console.log('\nThrough mneva-connect, with a valid key:');
+{
+  const c = await connector(key);
+
+  const tools = (await c.client.listTools()).tools.map((t) => t.name).sort();
+  check('connector exposes all six tools',
+    JSON.stringify(tools) === JSON.stringify(['assess', 'believe', 'flag', 'recall', 'remember', 'revise']),
+    `got ${JSON.stringify(tools)}`);
+
+  await c.call('remember', { text: 'the deploy script is scripts/ship.sh and needs the staging DB up first' });
+  const recalled = await c.call('recall', { query: 'how do we release' });
+  const hits = recalled.data?.results ?? [];
+  check('remember -> recall reaches the hosted brain (semantic)',
+    hits.some((m) => m.text.includes('ship.sh')),
+    JSON.stringify(recalled.data));
+
+  await c.call('flag', { text: 'the migration runner has dropped columns before — never run it without a backup' });
+  const verdict = await c.call('assess', { topic: 'about to run a database migration' });
+  check('flag -> assess works through the connector',
+    verdict.data?.verdict === 'danger',
+    JSON.stringify(verdict.data));
+  console.log(`   > assess verdict: ${verdict.data?.verdict} — "${verdict.data?.why}"`);
+
+  await c.end();
+}
+
+// 3. An invalid key must fail loudly, not silently.
+console.log('\nWith an invalid key:');
+{
+  const c = await connector('mnv_not_a_real_key');
+  const res = await c.call('recall', { query: 'anything' });
+  check('invalid key produces a clear error', res.isError === true && /invalid/i.test(res.data),
+    JSON.stringify(res));
+  await c.end();
+}
+
+console.log(`\n${'='.repeat(46)}`);
+console.log(`RESULT:  ${pass} passed, ${fail} failed`);
+console.log(fail === 0
+  ? 'mneva-connect works — the signup snippet is true.'
+  : 'mneva-connect NOT proven — see failures above.');
+console.log('='.repeat(46) + '\n');
+
+process.exit(fail === 0 ? 0 : 1);